ComponentExample

Usage

ComponentExample is used to embed interactive component examples in your documentation. It automatically loads the component and shows a live preview alongside the source code.

Basic usage

Use the :component-example directive in your Markdown documentation:

<script setup lang="ts">
import type { AccordionItem } from '@nuxt/ui'

const items = [
  {
    label: 'Icons',
    icon: 'i-lucide-smile',
    content: 'You have nothing to do, @nuxt/icon will handle it automatically.'
  },
  {
    label: 'Colors',
    icon: 'i-lucide-swatch-book',
    slot: 'colors' as const,
    content: 'Choose a primary and a neutral color from your Tailwind CSS theme.'
  },
  {
    label: 'Components',
    icon: 'i-lucide-box',
    content: 'You can customize components by using the `class` / `ui` props or in your app.config.ts.'
  }
] satisfies AccordionItem[]
</script>

<template>
  <UAccordion :items="items">
    <template #colors="{ item }">
      <p class="text-sm pb-3.5 text-primary">
        {{ item.content }}
      </p>
    </template>
  </UAccordion>
</template>

:component-example{name="AccordionExample"}

Advanced configuration

::component-example
---
name: AccordionExample
highlights: [10, 15, 20]
collapse: true
---
::

Client-only rendering

If the example uses browser APIs such as window, document, or setInterval directly, you can add client-only="true" so the preview component renders only on the client, avoiding warnings during the SSR phase:

:component-example{name="AccordionExample" client-only="true"}

API

Props

Slots

ComponentExampleExtras

Create app/components/content/ComponentExampleExtras.vue in the consumer repository to overlay additional UI such as ThemeVisualizer or a Playground button inside the example container, without forking ComponentExample. The layer provides an empty implementation by default.

Available props:

Example: overlaying ThemeVisualizer

Following Nuxt UI's ComponentThemeVisualizer.vue, implement a LazyComponentThemeVisualizer, then wire it up in the override file.

<script setup lang="ts">
import { camelCase } from 'scule'

defineProps<{
  wrapperContainer: HTMLElement | null
  componentContainer: HTMLElement | null
}>()

const route = useRoute()
const slug = computed(() => camelCase(route.path.split('/').pop() ?? ''))
</script>

<template>
  <LazyComponentThemeVisualizer
    :slug="slug"
    :container="componentContainer"
    :position-container="wrapperContainer"
  />
</template>

Changelog