ComponentExample
ComponentExample renders a live preview of an example component and shows the source of that example file below it. The source is read at build time, so it always matches the preview.
Writing examples
Put examples in app/components/content/examples/ (subdirectories are allowed). The file name is the example name:
app/components/content/examples/
└── AccordionExample.vue
Pass the file name to name, in PascalCase or kebab-case:
<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"}
Source display
Highlights and collapsing
highlights highlights the given lines and collapse folds long sources:
::component-example
---
name: AccordionExample
highlights: [2, 9]
collapse: true
---
::
collapse also accepts an object to customize the button labels and initial state:
::component-example
---
name: AccordionExample
collapse:
openText: Show source
closeText: Hide source
---
::
Preview or source only
source: falserenders only the previewpreview: falseshows only the source with the file name in the header; override it withfilenameprettier: trueformats the source with Prettier before displaying it
Adjustable options
options renders controls above the preview and passes the selected values to the example as props. Options whose name ends with color show color swatches:
::component-example
---
name: ButtonExample
options:
- name: color
label: color
items: [primary, secondary, neutral]
default: primary
- name: label
label: label
default: Button
---
::
props passes fixed initial props, merged with options.
Client-only rendering
When an example uses browser APIs such as window, document or setInterval directly, set client-only so the preview renders only on the client and avoids SSR errors:
:component-example{name="AccordionExample" client-only}
Extending the example container
Create app/components/content/ComponentExampleExtras.vue in your project to overlay extra UI (theme visualizers, playground buttons and so on) inside every example container. The layer ships an empty implementation, and ComponentCode renders it too.
| Prop | Type | Description |
|---|---|---|
name | string | The raw name value |
camelName | string | The example name in camelCase |
pascalName | string | The example name in PascalCase |
effectiveProps | Record<string, any> | Current values of props merged with options |
options | Array<{ name: string, label: string }> | undefined | options passed through as is |
wrapperContainer | HTMLElement | null | Outer container of the example, for positioning overlays |
componentContainer | HTMLElement | null | Container the example renders into, for scanning the DOM |
The following example, based on Nuxt UI's ComponentThemeVisualizer.vue, overlays a theme visualizer on each example:
<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>
The extension renders on the client only and does not affect SSR output.
API
Props
| Prop | Default | Type |
|---|---|---|
name | string | |
iframe | false | boolean | { [key: string]: any; } 是否在 iframe 中渲染组件 |
iframeMobile | false | boolean 是否在移动端尺寸的 iframe 视口中显示组件 |
props | { [key: string]: any; } | |
prettier | false | boolean 是否使用 Prettier 格式化代码 |
collapse | false | boolean | { icon?: string ; name?: string | undefined; openText?: string | undefined; closeText?: string | undefined; open?: boolean | undefined; } | undefined是否折叠代码块 |
preview | true | boolean 是否显示预览
当设置为 |
source | true | boolean 是否显示源代码 |
options | { type?: string | undefined; alias?: string | undefined; name: string; label: string; items?: any[] | undefined; default: any; multiple?: boolean | undefined; }[]链接到组件的可变属性列表 | |
highlights | number[]代码块中需要高亮的行号列表 | |
overflowHidden | boolean 是否在包装器上添加 overflow-hidden | |
clientOnly | false | boolean 是否只在客户端渲染预览组件,适用于依赖 window / setInterval 等浏览器 API 的示例 |
elevated | boolean 是否添加 background-elevated 到 wrapper | |
lang | 'vue' | string |
filename | string覆盖用于代码块的文件名 |
Slots
| Slot | Type |
|---|---|
options | {} |
code | {} |
Changelog
ComponentEmits
List every event of a Vue component with a single `:component-emits` line. Event names, parameter signatures and JSDoc descriptions come from the `defineEmits` type and complete the API docs next to the props and slots tables.
ComponentCode
Drive any registered Vue component from a props matrix with `::component-code`. Readers switch prop values above the live preview and the Vue snippet below updates in sync, ready to copy.