Field & Field Group

Display component props or configuration options in a beautiful, readable format instead of traditional tables.

Introduction

The Field and Field Group components provide an elegant way to document component props, configuration options, or any structured data. Instead of cramped tables, these components offer a spacious, readable layout with support for markdown content, badges, and flexible styling options.

Field

The ProseField component displays a single property or configuration item with its name, type, description, and default value.

Basic Usage

variantstringrequired

Defaultdefault

The visual style variant of the component.

Required Field

Mark important fields as required with the required prop.

onSubmit() => voidrequired

Callback function called when the form is submitted.

Complex Type

Display complex types like unions or function signatures.

sizesm | md | lg | xl

Defaultmd

Controls the size of the component. Accepts predefined size values.

With Markdown Description

Use the default slot to provide rich markdown content as the description.

themeobject

Default{}

The theme configuration object. You can customize:

primaryColor - Main theme color
borderRadius - Corner radius (0-20px)
fontFamily - Custom font stack

Example:

{
  primaryColor: '#3b82f6',
  borderRadius: 8,
  fontFamily: 'Inter, sans-serif'
}

Provide additional context with a tooltip using the tip prop.

You can display a custom icon in the tooltip using the tip-icon prop.

isOpenboolean

Defaultfalse

Indicates if the modal dialog is currently open.

Custom Name Slot

Override the name display with custom content using the #name slot.

v-model:openboolean

Defaultfalse

Controlled open state of the dialog component.

Custom Default Value Slot

Provide custom rendering for default values using the #default-value slot.

colors

Default

An example of using a custom default value slot.

Field Group

The ProseFieldGroup component is a container for multiple ProseField components, providing consistent layout and optional styling variants.

Basic Field Group

Group related fields together in a clean column layout.

variantstring

Defaultdefault

The visual style variant of the button.

sizestring

Defaultmd

Controls the size of the button.

disabledboolean

Defaultfalse

Whether the button is disabled.

Bordered Fields

Add visual separators between fields using the bordered variant.

openboolean

Defaultfalse

Controls the open state of the dialog.

modalboolean

Defaulttrue

Whether the dialog should be modal.

onClose() => void

Callback when the dialog closes.

Striped Background

Use alternating backgrounds to improve readability with the striped variant.

placeholderstring

Placeholder text for the input.

valuestring

The input value.

onChange(value: string) => void

Callback when value changes.

disabledboolean

Defaultfalse

Whether the input is disabled.

All Variants Combined

Combine bordered, divided, and striped for maximum visual organization with the all variant.

itemsArray<Item>required

Array of items to display in the list.

selectedIdstring | null

Defaultnull

The ID of the currently selected item.

onSelect(item: Item) => void

Callback when an item is selected.

loadingboolean

Defaultfalse

Whether the list is in a loading state.

emptyMessagestring

DefaultNo items found

Message to show when the list is empty.

Real-World Example

Here's how you might document a complete component API:

Button Props

variantdefault | destructive | outline | ghost | link

Defaultdefault

The visual style variant of the button.

default - Standard button appearance
destructive - Red/danger styling for destructive actions
outline - Outlined button with transparent background
ghost - Minimal styling with hover effect
link - Styled as a hyperlink

sizesm | md | lg | icon

Defaultmd

Controls the size and padding of the button.

disabledboolean

Defaultfalse

When true, the button cannot be interacted with and appears visually disabled.

loadingboolean

Defaultfalse

Shows a loading spinner and disables the button while an async action is in progress.

onClick(event: MouseEvent) => void

Callback function triggered when the button is clicked.

Use Cases

The Field and Field Group components are perfect for:

Component Props Documentation - Document Vue/React component props in a readable format
API Configuration - Show configuration options for libraries or APIs
Function Parameters - Document function signatures and parameters
Type Definitions - Display TypeScript interface or type properties
CLI Options - Document command-line interface options and flags
Environment Variables - List and explain required environment variables

Best Practices

1. Use Descriptive Types

Be specific with type definitions to help users understand what values are valid:

<!-- ❌ Too vague -->

::prose-field{name="color" type="string"}

<!-- ✅ Better -->

::prose-field{name="color" type="'red' | 'blue' | 'green' | hex string"}

2. Provide Context in Descriptions

Use the default slot to add examples, lists, or additional context:

::prose-field{name="items" type="Array<Item>" required}
Array of items to display. Each item should have:

- `id` - Unique identifier
- `label` - Display text
- `icon` - Optional icon name
  ::

Use Field Groups to organize props by category:

### Style Props

::prose-field-group

<!-- Style-related fields -->

::

### Behavior Props

::prose-field-group

<!-- Behavior-related fields -->

::

4. Combine Variants Wisely

Use divided for clear separation
Use striped for long lists
Use bordered to make sections distinct
Combine all three for maximum organization in complex documentation

5. Mark Required Fields Consistently

Always use the required prop for mandatory fields to help users identify what's necessary at a glance.

Collapsible

Hide and reveal content with a collapsible component featuring customizable icons and labels.

Icon List

Display lists with custom icons and variants for each item.