ComponentExample

Render a Vue file from the examples directory as a live preview with its highlighted source below. Supports line highlights, collapsing, adjustable options and client-only rendering for showing components in realistic compositions.

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.

Requires movkNuxtDocs.componentDocs, with the same prerequisites as ComponentProps.

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: false renders only the preview
  • preview: false shows only the source with the file name in the header; override it with filename
  • prettier: true formats 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.

PropTypeDescription
namestringThe raw name value
camelNamestringThe example name in camelCase
pascalNamestringThe example name in PascalCase
effectivePropsRecord<string, any>Current values of props merged with options
optionsArray<{ name: string, label: string }> | undefinedoptions passed through as is
wrapperContainerHTMLElement | nullOuter container of the example, for positioning overlays
componentContainerHTMLElement | nullContainer 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:

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>

The extension renders on the client only and does not affect SSR output.

API

Props

Prop Default Type
namestring
iframefalseboolean | { [key: string]: any; }

是否在 iframe 中渲染组件

iframeMobilefalseboolean

是否在移动端尺寸的 iframe 视口中显示组件

props { [key: string]: any; }
prettierfalseboolean

是否使用 Prettier 格式化代码

collapsefalseboolean | { icon?: string ; name?: string | undefined; openText?: string | undefined; closeText?: string | undefined; open?: boolean | undefined; } | undefined

是否折叠代码块

previewtrueboolean

是否显示预览 当设置为 false 时,将显示文件名

sourcetrueboolean

是否显示源代码

options { type?: string | undefined; alias?: string | undefined; name: string; label: string; items?: any[] | undefined; default: any; multiple?: boolean | undefined; }[]

链接到组件的可变属性列表

highlights number[]

代码块中需要高亮的行号列表

overflowHiddenboolean

是否在包装器上添加 overflow-hidden

clientOnlyfalseboolean

是否只在客户端渲染预览组件,适用于依赖 window / setInterval 等浏览器 API 的示例

elevatedboolean

是否添加 background-elevated 到 wrapper

lang'vue' string
filename string

覆盖用于代码块的文件名

Slots

Slot Type
options{}
code{}

Changelog

No recent changes
Copyright © 2024 - 2026