Layout Examples

Organize your controls with groups, grids, and flexible layouts. See live examples of each layout type.

Interactive Layout Examples

Explore different layout configurations:

/**
 * @dial transform
 * @dial-layout grid
 * @dial-cols 3
 */

Layout Types

Grid Layout

The most common layout type. Arrange controls in a grid with specified columns.

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

  /**
   * Y position
   * @dial transform
   */
  y: number;

  /**
   * Z position
   * @dial transform
   */
  z: number;
}

Result: All three controls appear in a single row with 3 columns.

Flex Layout

Use flexbox for more dynamic layouts.

interface Props {
  /**
   * Primary action
   * @dial actions
   * @dial-layout flex
   * @dial-direction row
   * @dial-gap 8px
   */
  save: boolean;

  /**
   * Secondary action
   * @dial actions
   */
  cancel: boolean;
}

Column Layouts

2-Column Layout

/**
 * @dial appearance
 * @dial-cols 2
 */

3-Column Layout

/**
 * @dial geometry
 * @dial-cols 3
 */

4-Column Layout

/**
 * @dial grid
 * @dial-cols 4
 */

Group Annotations

Basic Group Configuration

interface Props {
  /**
   * Property 1
   * @dial myGroup
   * @dial-layout grid
   * @dial-cols 2
   * @dial-rows 2
   */
  prop1: number;

  /**
   * Property 2
   * @dial myGroup
   */
  prop2: number;

  /**
   * Property 3
   * @dial myGroup
   */
  prop3: number;

  /**
   * Property 4
   * @dial myGroup
   */
  prop4: number;
}

Available Group Annotations

Shorthand Annotations

// Grid layout shorthands
@dial-layout grid       // Same as @dial-group-layout grid
@dial-cols 3           // Same as @dial-group-grid-cols 3
@dial-grid-cols 3      // Alternative: same as @dial-group-grid-cols 3
@dial-rows 2           // Same as @dial-group-grid-rows 2
@dial-grid-rows 2      // Alternative: same as @dial-group-grid-rows 2

// Flex layout shorthands
@dial-wrap wrap        // Same as @dial-group-flex-wrap wrap
@dial-flex-wrap wrap   // Alternative: same as @dial-group-flex-wrap wrap
@dial-justify center   // Same as @dial-group-flex-justify-content center
@dial-flex-justify-content center  // Alternative: same as @dial-group-flex-justify-content center

Layout Patterns

Transform Controls (3-Column)

interface Transform3DProps {
  /**
   * @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;

  /** @dial transform @dial-icon RotateCw */
  rotX: number;

  /** @dial transform */
  rotY: number;

  /** @dial transform */
  rotZ: number;

  /** @dial transform @dial-icon Scaling */
  scaleX: number;

  /** @dial transform */
  scaleY: number;

  /** @dial transform */
  scaleZ: number;
}

Appearance Controls (2-Column)

interface AppearanceProps {
  /**
   * @dial appearance
   * @dial-cols 2
   * @dial-dtype color
   */
  primaryColor: string;

  /**
   * @dial appearance
   * @dial-dtype color
   */
  secondaryColor: string;

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

  /**
   * @dial appearance
   * @dial-dtype boolean
   */
  visible: boolean;
}

Settings Panel (Mixed Layout)

interface SettingsProps {
  // Graphics section - 2 columns
  /**
   * @dial graphics
   * @dial-cols 2
   * @dial-dtype select
   * @dial-options ["low", "medium", "high", "ultra"]
   */
  quality: string;

  /** @dial graphics @dial-dtype boolean */
  shadows: boolean;

  /** @dial graphics @dial-dtype boolean */
  reflections: boolean;

  /** @dial graphics @dial-dtype boolean */
  antialiasing: boolean;

  // Audio section - single column
  /**
   * @dial audio
   * @dial-cols 1
   * @dial-min 0 @dial-max 100
   */
  masterVolume: number;

  /** @dial audio @dial-min 0 @dial-max 100 */
  musicVolume: number;

  /** @dial audio @dial-min 0 @dial-max 100 */
  sfxVolume: number;
}

Property-Level Layout

Individual properties can span multiple columns/rows:

interface Props {
  /**
   * Wide control
   * @dial layout-test
   * @dial-cols 2
   * @dial-col-span 2
   */
  wideControl: string;

  /** @dial layout-test */
  normal1: number;

  /** @dial layout-test */
  normal2: number;

  /**
   * Tall control
   * @dial layout-test
   * @dial-row-span 2
   */
  tallControl: number;
}

Complex Layout Example

// Complete example with multiple groups
interface ComplexUIProps {
  // Transform group - 3 columns
  /**
   * @dial transform
   * @dial-layout grid
   * @dial-cols 3
   * @dial-dtype vector3
   * @dial-col-span 3
   */
  position: [number, number, number];

  /** @dial transform @dial-dtype number */
  rotX: number;

  /** @dial transform @dial-dtype number */
  rotY: number;

  /** @dial transform @dial-dtype number */
  rotZ: number;

  // Appearance group - 2 columns
  /**
   * @dial appearance
   * @dial-cols 2
   * @dial-dtype color
   */
  color: string;

  /** @dial appearance @dial-dtype number @dial-min 0 @dial-max 1 */
  opacity: number;

  /** @dial appearance @dial-dtype boolean */
  visible: boolean;

  /** @dial appearance @dial-dtype boolean */
  wireframe: boolean;

  // Settings group - flexible
  /**
   * @dial settings
   * @dial-layout flex
   * @dial-direction column
   * @dial-gap 12px
   * @dial-dtype select
   * @dial-options ["auto", "manual"]
   */
  mode: string;

  /** @dial settings @dial-dtype int @dial-min 1 @dial-max 10 */
  level: number;
}

Group Configuration in Code

When using generated schemas, you can customize groups programmatically:

const groups: GroupSchema[] = [
  {
    name: 'transform',
    label: 'Transform',
    layout: 'grid',
    gridCols: 3,
    collapsible: true
  },
  {
    name: 'appearance',
    label: 'Appearance',
    layout: 'grid',
    gridCols: 2,
    collapsible: true,
    defaultCollapsed: false
  },
  {
    name: 'advanced',
    label: 'Advanced Settings',
    layout: 'flex',
    flexDirection: 'column',
    collapsible: true,
    defaultCollapsed: true
  }
];

<DialPanel schemas={schemas} groups={groups} />

Best Practices

1. Use consistent column counts within a group for visual harmony

2. Group related properties together (transform, appearance, physics, etc.)

3. Consider property types when choosing layouts:

   • Vectors work well in single rows
   • Toggles pair well in 2-column layouts
   • Sliders often need full width

4. Use collapsible groups for advanced or less-used settings

5. Test responsive behavior with different viewport sizes

Next Steps