---
title: "ComponentExample"
description: "ComponentExample embeds interactive Vue component examples in your documentation, rendering a live preview and displaying syntax-highlighted source code with collapsible support. It fetches example files registered at build time via useFetchComponentExample, significantly improving the readability and user experience of your docs."
canonical_url: "https://docs.mhaibaraai.cn/en/docs/components/component-example"
---
# ComponentExample

> ComponentExample embeds interactive Vue component examples in your documentation, rendering a live preview and displaying syntax-highlighted source code with collapsible support. It fetches example files registered at build time via useFetchComponentExample, significantly improving the readability and user experience of your docs.

## 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:

```vue
<template>
  <pre language=vue code=<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>
   filename=AccordionExample.vue />
  <template v-slot:code=>
  <pre className=language-mdc shiki shiki-themes material-theme-lighter material-theme material-theme-palenight code=:component-example{name="AccordionExample"}
   language=mdc meta= style=>
  <code __ignoreMap=>
  <span class=line>
  <span class=sMK4o>
  :</span>
  <span class=swJcz>
  component-example</span>
  <span class=sMK4o>
  {</span>
  <span class=spNyl>
  name</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  AccordionExample</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  }
  </span></span></code></pre></template>
</template>
```

### Advanced configuration

```md [md]
::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:

```md [md]
:component-example{name="AccordionExample" client-only="true"}
```

## API

### Props

```ts
/**
 * Props for the ComponentExample component
 */
interface ComponentExampleProps {
  name: string;
  /**
   * 是否在 iframe 中渲染组件
   */
  iframe?: boolean | { [key: string]: any; } | undefined;
  /**
   * 是否在移动端尺寸的 iframe 视口中显示组件
   */
  iframeMobile?: boolean | undefined;
  props?: { [key: string]: any; } | undefined;
  /**
   * 是否使用 Prettier 格式化代码
   * @default "false"
   */
  prettier?: boolean | undefined;
  /**
   * 是否折叠代码块
   */
  collapse?: boolean | { icon?: string | undefined; name?: string | undefined; openText?: string | undefined; closeText?: string | undefined; open?: boolean | undefined; } | undefined;
  /**
   * 是否显示预览
   * 当设置为 `false` 时，将显示文件名
   * @default "true"
   */
  preview?: boolean | undefined;
  /**
   * 是否显示源代码
   * @default "true"
   */
  source?: boolean | undefined;
  /**
   * 链接到组件的可变属性列表
   */
  options?: { type?: string | undefined; alias?: string | undefined; name: string; label: string; items?: any[] | undefined; default: any; multiple?: boolean | undefined; }[] | undefined;
  /**
   * 代码块中需要高亮的行号列表
   */
  highlights?: number[] | undefined;
  /**
   * 是否在包装器上添加 overflow-hidden
   */
  overflowHidden?: boolean | undefined;
  /**
   * 是否只在客户端渲染预览组件，适用于依赖 window / setInterval 等浏览器 API 的示例
   */
  clientOnly?: boolean | undefined;
  /**
   * 是否添加 background-elevated 到 wrapper
   */
  elevated?: boolean | undefined;
  /**
   * @default "\"vue\""
   */
  lang?: string | undefined;
  /**
   * 覆盖用于代码块的文件名
   */
  filename?: string | undefined;
}
```

### Slots

```ts
/**
 * Slots for the ComponentExample component
 */
interface ComponentExampleSlots {
  options(): any;
  code(): any;
}
```

## `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:

<table>
<thead>
  <tr>
    <th>
      Prop
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      <code className="language-ts-type shiki shiki-themes material-theme-lighter material-theme material-theme-palenight" language="ts-type" style="">
        <span class="sBMFI">
          string
        </span>
      </code>
    </td>
    
    <td>
      The raw value of the MDC <code>
        name="..."
      </code>
      
      , i.e. the example filename
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        camelName
      </code>
    </td>
    
    <td>
      <code className="language-ts-type shiki shiki-themes material-theme-lighter material-theme material-theme-palenight" language="ts-type" style="">
        <span class="sBMFI">
          string
        </span>
      </code>
    </td>
    
    <td>
      The camelCase form of the example name
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pascalName
      </code>
    </td>
    
    <td>
      <code className="language-ts-type shiki shiki-themes material-theme-lighter material-theme material-theme-palenight" language="ts-type" style="">
        <span class="sBMFI">
          string
        </span>
      </code>
    </td>
    
    <td>
      The PascalCase form of the example name, from <code>
        useFetchComponentExample
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        effectiveProps
      </code>
    </td>
    
    <td>
      <code className="language-ts-type shiki shiki-themes material-theme-lighter material-theme material-theme-palenight" language="ts-type" style="">
        <span class="sBMFI">
          Record
        </span>
        
        <span class="sMK4o">
          <
        </span>
        
        <span class="sBMFI">
          string
        </span>
        
        <span class="sMK4o">
          ,
        </span>
        
        <span class="sBMFI">
          any
        </span>
        
        <span class="sMK4o">
          >
        </span>
      </code>
    </td>
    
    <td>
      The currently effective merged props (including options)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options
      </code>
    </td>
    
    <td>
      <code className="language-ts-type shiki shiki-themes material-theme-lighter material-theme material-theme-palenight" language="ts-type" style="">
        <span class="sBMFI">
          Array
        </span>
        
        <span class="sMK4o">
          <{
        </span>
        
        <span class="swJcz">
          name
        </span>
        
        <span class="sMK4o">
          ,
        </span>
        
        <span class="swJcz">
          label
        </span>
        
        <span class="sMK4o">
          ,
        </span>
        
        <span class="sMK4o">
          ...
        </span>
        
        <span class="sMK4o">
          }>
        </span>
        
        <span class="sMK4o">
          |
        </span>
        
        <span class="sBMFI">
          undefined
        </span>
      </code>
    </td>
    
    <td>
      The options configuration, passed through as-is
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        wrapperContainer
      </code>
    </td>
    
    <td>
      <code className="language-ts-type shiki shiki-themes material-theme-lighter material-theme material-theme-palenight" language="ts-type" style="">
        <span class="sBMFI">
          HTMLElement
        </span>
        
        <span class="sMK4o">
          |
        </span>
        
        <span class="sBMFI">
          null
        </span>
      </code>
    </td>
    
    <td>
      The outermost wrapper, used for popover / highlight box positioning
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        componentContainer
      </code>
    </td>
    
    <td>
      <code className="language-ts-type shiki shiki-themes material-theme-lighter material-theme material-theme-palenight" language="ts-type" style="">
        <span class="sBMFI">
          HTMLElement
        </span>
        
        <span class="sMK4o">
          |
        </span>
        
        <span class="sBMFI">
          null
        </span>
      </code>
    </td>
    
    <td>
      The actual render container of the example component, used for DOM scanning such as <code>
        querySelector('[data-slot]')
      </code>
    </td>
  </tr>
</tbody>
</table>

### Example: overlaying ThemeVisualizer

Following [Nuxt UI's `ComponentThemeVisualizer.vue`](https://github.com/nuxt/ui/blob/v4/docs/app/components/content/ComponentThemeVisualizer.vue), implement a `LazyComponentThemeVisualizer`, then wire it up in the override file.

```vue [docs/app/components/content/ComponentExampleExtras.vue]
<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

See commit history for [layer/app/components/content/ComponentExample.vue](https://github.com/mhaibaraai/movk-nuxt-docs/commits/main/layer/app/components/content/ComponentExample.vue).

---

- [GitHub](https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/app/components/content/ComponentExample.vue)


## Sitemap

See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.