Authoring components

Component Metadata

DOM Studio reads your Vue props to build documentation and editing controls. Add optional metadata to describe your components and refine how they are edited.

Use this guide when adding or adapting components in DOM Studio. For components in your application, start with the installation guide and their props, slots, and events. Metadata is optional for ordinary Vue usage; installing the package does not add a docs site to your app.

See the metadata at work

This is the real DomStatusPill component. Change its label, choose a tone, or toggle the dot. Vue prop types supply the text and toggle controls; _edit.options supplies the choices.

Status pill

Edit the properties to update the component and its usage example.

Live

Playground.vuevue

Install

npm install @getdom/studio

vue

<script setup>
import '@getdom/studio/style.css';
import { reactive } from 'vue';
import { DomStatusPill } from '@getdom/studio';

const data = reactive({
		"tone": "success",
		"label": "Live",
		"size": "md",
		"variant": "soft",
		"dot": true,
		"pulse": false
	});
</script>

<template>
	<DomStatusPill
		v-bind="data"
	/>
</template>

View the complete component source

vue

<script setup>
import { computed } from 'vue';
import DomBadge from '../badge/DomBadge.vue';

defineOptions({
	__doc: {
		name: 'Status pill',
		tag: '<DomStatusPill>',
		description: 'A badge with an optional status dot for live state, severity, and workflow labels.',
		playground: {
			initial: { label: 'Live', tone: 'success', dot: true },
		},
		slots: [
			{ name: '(default)', description: 'Status label.' },
		],
	},
});

const props = defineProps({
	tone: {
		type: String,
		default: 'neutral',
		_edit: {
			options: ['neutral', 'primary', 'success', 'warning', 'danger', 'info'],
			description: 'Semantic status tone.',
		},
	},
	label: {
		type: String,
		default: 'Status',
		_edit: { description: 'Fallback label when no default slot is provided.' },
	},
	size: {
		type: String,
		default: 'md',
		_edit: { options: ['sm', 'md', 'lg'], description: 'Pill density.' },
	},
	variant: {
		type: String,
		default: 'soft',
		_edit: { options: ['soft', 'solid', 'outline'], description: 'Visual weight.' },
	},
	dot: {
		type: Boolean,
		default: true,
		_edit: { description: 'Show a leading state dot.' },
	},
	pulse: {
		type: Boolean,
		default: false,
		_edit: { description: 'Animate the dot for live or active states.' },
	},
});

const dotClasses = computed(() => ({
	neutral: 'bg-muted-fg',
	primary: 'bg-primary',
	success: 'bg-success',
	warning: 'bg-warning',
	danger: 'bg-destructive',
	info: 'bg-primary',
}[props.tone] || 'bg-muted-fg'));
</script>

<template>
	<DomBadge :tone="tone" :size="size" :variant="variant">
		<span
			v-if="dot"
			class="size-1.5 rounded-full"
			:class="[dotClasses, pulse && 'animate-pulse']"
			aria-hidden="true"
		></span>
		<slot>{{ label }}</slot>
	</DomBadge>
</template>

The source above is loaded from the same file as the preview. Open the full status pill reference.

Describe the component with __doc

Add __doc inside defineOptions() in your component's script setup. Start with a name and description, then document slots and events as needed.

defineOptions({
	__doc: {
		name: 'Status pill',
		tag: '<DomStatusPill>',
		description: 'A compact label for workflow status.',
		playground: {
			initial: { label: 'Live', tone: 'success' },
		},
		slots: [
			{ name: '(default)', description: 'Status label.' },
		],
	},
});

name: Readable component name for documentation and navigation.
description: A short explanation of what the component does and when to use it.
tag: The component tag shown in documentation and generated usage examples.
playground.initial: Starting prop values for the generated playground. These override the component defaults in the demo only.
slots: Slot descriptions, with optional payloads for scoped slots.
events: Event descriptions and payloads. Event names are also read from Vue emits and component source.
keyboard: Key and action pairs for pages that include the keyboard reference helper.
icon / order / badge: An SVG path, numeric ordering hint, and optional badge for the component catalogue.
nav: Navigation overrides: icon, badge, and hidden.
studio: Palette settings such as group, icon, hidden, defaults, accepts, and editor hints.
hidden: Hides the component from navigation and the Studio palette. This does not disable its route or package export.

Documenting an input event

Declare events with Vue's defineEmits(), and describe their meaning in __doc.events. For an input component, an entry might look like this:

defineOptions({
	__doc: {
		events: [
			{
				name: 'update:modelValue',
				payload: 'string',
				description: 'The current text after editing.',
			},
		],
	},
});

const emit = defineEmits(['update:modelValue']);

Metadata documents the event; the component still needs to emit it when its value changes.

Choose editing controls with _edit

String, number, and boolean props get basic editors automatically. Put _edit on a prop definition to add help text, provide choices, or use a richer editor. These hints configure the inspector; they do not validate the prop at runtime.

const props = defineProps({
	tone: {
		type: String,
		default: 'neutral',
		_edit: {
			options: ['neutral', 'success', 'warning', 'danger'],
			description: 'Visual state shown by the pill.',
		},
	},
});

description: Helper text for the prop reference and inspector field.
options: Available choices. Uses a select editor when no editor component is specified.
component: An inspector editor name, such as DomTextInput, DomJsonInput, or DomJsonListInput.
props: Configuration passed to that editor, such as rows, compact, or schema.
label: A readable field label. Defaults to a label derived from the prop name.
group: An optional group heading for related fields in the playground.

Array and object props need an explicit editor, such as DomJsonInput or DomJsonListInput, or a choices hint. Use JSDoc @typedef and @type comments in the source to describe their data shapes in the prop reference.

Add a component to this repository

Add a Dom*.vue file in a component folder under components, data, charts, dev, forms, mobile, or visual.
Run the dev server. The generated catalogue supplies the route and navigation entry; a playground and prop reference are created when the folder has no Index.vue.
Add metadata where it helps. Keep examples beside the component, and add an Index.vue when you need an authored documentation page.
For a public package component, add its export to src/pages/lib/vue/index.js and run npm run types:generate.

The docs engine is part of this repository. Reusing it in another app requires its catalogue generation, loaders, routing, and documentation helpers.

For composing and saving UI layouts, explore Studio. Saved layout data has a separate renderer format from the component metadata described here.