Annotations Reference

Complete reference for all @dial annotations. These JSDoc comments control how your UI is generated.

Quick Reference

/**
 * Property description
 * @dial <group>               // Assign to group
 * @dial-dtype <type>          // Data type
 * @dial-label <text>          // Display label
 * @dial-icon <name>           // Lucide icon
 * @dial-min <number>          // Min value
 * @dial-max <number>          // Max value
 * @dial-step <number>         // Step increment
 * @dial-options [...]         // Select options
 * @dial-value <default>       // Default value
 * @dial-order <number>        // Display order in group
 * @dial-group-order <number>  // Group display order
 */
propertyName: type;

Property Annotations

Core Annotations

Display Annotations

Numeric Constraints

Vector-Specific Annotations

For tuple/vector types with per-element settings.

Label Position Annotations

Layout Annotations

Ordering Annotations

Control the display order of properties and groups in the generated UI.

Group Annotations

Apply to the first property in a group to configure the entire group layout.

Layout Configuration

Shorthand Group Annotations

Supported Data Types

Examples

Basic Property with All Annotations

interface Props {
  /**
   * Component opacity
   * @dial appearance
   * @dial-dtype number
   * @dial-label "Transparency"
   * @dial-icon Opacity
   * @dial-min 0
   * @dial-max 1
   * @dial-step 0.01
   * @dial-value 1
   * @dial-tooltip "Controls the transparency of the element"
   */
  opacity: number;
}

Group with Layout

interface Props {
  /**
   * X position
   * @dial transform
   * @dial-layout grid
   * @dial-cols 3
   * @dial-icon ArrowRight
   */
  x: number;

  /** @dial transform @dial-icon ArrowUp */
  y: number;

  /** @dial transform @dial-icon ArrowUpRight */
  z: number;
}

Vector with Per-Element Constraints

type RGB = [
  // @dial-min 0 @dial-max 255 @dial-step 1 @dial-dtype int
  r: number,
  // @dial-min 0 @dial-max 255 @dial-step 1 @dial-dtype int
  g: number,
  // @dial-min 0 @dial-max 255 @dial-step 1 @dial-dtype int
  b: number,
];

interface Props {
  /**
   * RGB Color
   * @dial appearance
   * @dial-icon Palette
   * @dial-placeholders ["Red", "Green", "Blue"]
   */
  color: RGB;
}

Select with Options

interface Props {
  /**
   * Material type
   * @dial appearance
   * @dial-dtype select
   * @dial-options ["standard", "metallic", "glass", "emissive"]
   * @dial-icon Sparkles
   * @dial-value "standard"
   */
  material: string;
}

Component-Level Ignore

/**
 * Internal component - excluded from schema
 * @dial-ignore
 */
export const InternalComponent: FC<Props> = () => { };

Property and Group Ordering

interface OrderedProps {
  /**
   * Title - appears first in general group
   * @dial general
   * @dial-group-order 1  // general group appears first
   * @dial-order 1        // title appears first in general
   */
  title: string;

  /**
   * Description - appears second in general group
   * @dial general
   * @dial-order 2        // description appears second
   */
  description: string;

  /**
   * Theme - appears first in appearance group
   * @dial appearance
   * @dial-group-order 2  // appearance group appears second
   * @dial-order 1        // theme appears first in appearance
   */
  theme: string;

  /**
   * Color - appears after theme
   * @dial appearance
   * @dial-order 2        // color appears second
   */
  color: string;

  /**
   * Advanced setting - no explicit order
   * @dial general
   * // Will appear after ordered properties (title, description)
   */
  notes: string;
}

Complete Example

interface CompleteExample {
  // Transform group - 3 columns
  /**
   * 3D Position
   * @dial transform
   * @dial-layout grid
   * @dial-cols 3
   * @dial-dtype vector3
   * @dial-min -100
   * @dial-max 100
   * @dial-step 0.1
   * @dial-placeholders ["X", "Y", "Z"]
   * @dial-icon Move3d
   * @dial-col-span 3
   */
  position: [number, number, number];

  /** @dial transform @dial-dtype number @dial-min -180 @dial-max 180 */
  rotX: number;

  /** @dial transform @dial-dtype number @dial-min -180 @dial-max 180 */
  rotY: number;

  /** @dial transform @dial-dtype number @dial-min -180 @dial-max 180 */
  rotZ: number;

  // Appearance group - 2 columns
  /**
   * Primary color
   * @dial appearance
   * @dial-cols 2
   * @dial-dtype color
   * @dial-icon Palette
   * @dial-value "#3b82f6"
   */
  color: string;

  /**
   * Opacity
   * @dial appearance
   * @dial-dtype number
   * @dial-min 0
   * @dial-max 1
   * @dial-step 0.01
   * @dial-value 1
   */
  opacity: number;

  /**
   * Visible
   * @dial appearance
   * @dial-dtype boolean
   * @dial-icon Eye
   */
  visible: boolean;

  /**
   * Cast shadows
   * @dial appearance
   * @dial-dtype boolean
   * @dial-icon Moon
   */
  shadows: boolean;

  // Hidden property
  /**
   * Internal state
   * @dial-ignore
   */
  _internal: any;
}

Best Practices

1. Always specify dtype for clarity and correct control rendering
2. Group related properties using meaningful group names
3. Use descriptive labels when property names aren't clear
4. Set appropriate min/max/step for numeric values
5. Add icons to improve visual recognition
6. Use placeholders for text inputs and vector elements
7. Add tooltips for properties that need explanation
8. Use @dial-ignore for internal/private properties

Next Steps