![Nuxt Elements](https://user-images.githubusercontent.com/904724/182881577-5c94cc0f-c8b9-4005-b204-4b4c2e801f49.png)

# Nuxt Elements

The Vue components library to build any kind of websites, built with [design tokens](https://design-tokens.nuxtjs.org) and made to be used in [Markdown Components](https://content.nuxtjs.org/guide/writing/mdc).

- **Documentation:** [elements.nuxt.dev](https://elements.nuxt.dev) (password: `nuxtifytheworld`)
- **Online playground:** [stackblitz.com/edit/nuxt-elements-play](https://stackblitz.com/edit/nuxt-elements-play?file=content%2Findex.md)



## Usage

In your Nuxt project, install the package:

```bash
yarn add --dev @nuxt-themes/elements
```

Then in your `nuxt.config.ts`, add it to the `extends` array:

```ts
import { defineNuxtConfig } from 'nuxt'

export default defineNuxtConfig({
  extends: ['@nuxt-themes/elements']
})
```

Start using the elements to build your website, checkout the list of elements on [elements.nuxt.dev](https://elements.nuxt.dev).

### Edge channel

After each commit is merged into the `dev` branch and passing all tests, we trigger an automated npm release using Github Actions publishing on [@nuxt-themes/elements-edge](https://www.npmjs.com/package/@nuxt-themes/elements-edge).

You can opt-in to it by installing and using `@nuxt-themes/elements-edge` instead of `@nuxt-themes/elements`.

# Elements

An element is **a Vue component** made to be used inside the `content/` directory with the [MDC syntax](https://content.nuxtjs.org/guide/writing/mdc).

The component can have:
- Props to receive data from the editor (generated form)
- Slots using the [`<ContentSlot>`](https://content.nuxtjs.org/api/components/content-slot) component to pass MDC to the component

**Example:**

```vue
<script setup lang="ts">
defineProps({
  image: {
    type: String,
    default: null
  }
})
</script>

<template>
  <section>
      <h1 class="text-3xl font-bold text-primary-900 dark:text-primary-100">
        <ContentSlot :use="$slots.title" unwrap="p">Default title</ContentSlot>
      </h1>
      <!-- description slot is optional -->
      <p class="mt-3" v-if="$slots.description">
        <ContentSlot :use="$slots.description" unwrap="p" />
      </p>
      </div>
      <img v-if="image" :src="image" />
    </div>
  </section>
</template>
```

Note that the `<ContentSlot>` component cannot have `class` attribute because they are headless components.

## Development

Make sure to install the dependencies:

```bash
yarn install
```

Start the playground and documentation on http://localhost:3000

```bash
npm run dev
```

Generate the documentation:

```bash
npm run generate
```

Locally preview the generated documentation:

```bash
npm run preview
```

To use the elements in development in your project:
- Run the `pwd` command in the elements project and copy it, example: `/Users/atinux/Projects/nuxt-themes/elements`
- Add it to your `nuxt.config.ts` and suffix with `/theme`:


```ts
import { defineNuxtConfig } from 'nuxt'

export default defineNuxtConfig({
  extends: ['/Users/atinux/Projects/nuxt-themes/elements/theme']
})
```

### License

TBD