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

```mdc
:component-example{name="AccordionExample"}
```

### 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 中渲染组件
   * @default false
   */
  iframe?: boolean | { [key: string]: any; } | undefined;
  /**
   * 是否在移动端尺寸的 iframe 视口中显示组件
   * @default false
   */
  iframeMobile?: boolean | undefined;
  props?: { [key: string]: any; } | undefined;
  /**
   * 是否使用 Prettier 格式化代码
   * @default false
   */
  prettier?: boolean | undefined;
  /**
   * 是否折叠代码块
   * @default false
   */
  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 的示例
   * @default false
   */
  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:

| Prop | Type | Description |
| --- | --- | --- |
| `name` | `string` | The raw value of the MDC `name="..."`, i.e. the example filename |
| `camelName` | `string` | The camelCase form of the example name |
| `pascalName` | `string` | The PascalCase form of the example name, from `useFetchComponentExample` |
| `effectiveProps` | `Record<string, any>` | The currently effective merged props (including options) |
| `options` | `Array<{ name, label, ... }> \| undefined` | The options configuration, passed through as-is |
| `wrapperContainer` | `HTMLElement \| null` | The outermost wrapper, used for popover / highlight box positioning |
| `componentContainer` | `HTMLElement \| null` | The actual render container of the example component, used for DOM scanning such as `querySelector('[data-slot]')` |

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