Dial Input Types

Input Types Reference

dial-cliv0.0.22

The Dial system supports a comprehensive set of input types for different data formats and use cases. Each input type has specific properties and behaviors optimized for its data type.

Live Examples

Quick Start Example

Speed

Direction

Active

const schemas = [
  { name: 'speed', dtype: 'number', value: 50, min: 0, max: 100 },
  { name: 'direction', dtype: 'number-rad', value: 0 },
  { name: 'active', dtype: 'boolean', value: true },
];

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

Basic Types Example

Username

Age

Score

Angle

Enabled

Values: {}

const [values, setValues] = useState({});

const schemas = [
  { name: 'username', dtype: 'string', value: 'John Doe' },
  { name: 'age', dtype: 'number-int', value: 25, min: 0, max: 120 },
  { name: 'score', dtype: 'number', value: 85.5, min: 0, max: 100, step: 0.5 },
  { name: 'angle', dtype: 'number-rad', value: Math.PI / 4, step: 15 },
  { name: 'enabled', dtype: 'boolean', value: true },
];

const handleValueChange = (name, value) => {
  setValues(prev => ({ ...prev, [name]: value }));
};

<DialProvider schemas={schemas} onValueChange={handleValueChange}>
  <DialPanel schemas={schemas} />
</DialProvider>

Vector and Rotation Types Example

Transform

Position

Rotation

x°

y°

z°

RotationRad

x°

y°

z°

Scale

Values:

{}

const schemas = [
  {
    name: 'position',
    dtype: 'vector3',
    value: [0, 1, 0],
    min: -10,
    max: 10,
    step: 0.1,
    tags: { grouping: 'Transform', noWrap: true }
  },
  {
    name: 'rotation',
    dtype: 'euler',
    value: [0, 45, 0],
    step: 15,
    tags: { grouping: 'Transform', noWrap: true }
  },
  {
    name: 'rotationRad',
    dtype: 'euler-rad',
    value: [0, Math.PI/4, 0],
    step: 15,
    tags: { grouping: 'Transform', noWrap: true }
  },
  {
    name: 'scale',
    dtype: 'vector3',
    value: [1, 1, 1],
    min: 0.1,
    max: 5,
    step: 0.1,
    tags: { grouping: 'Transform', noWrap: true }
  }
];

const groups = [
  { name: 'Transform', noWrap: true }
];

<DialProvider schemas={schemas} onValueChange={handleValueChange}>
  <DialPanel schemas={schemas} groups={groups} />
</DialProvider>

Selection and Color Types Example

Appearance

Theme

Quality

BackgroundColor

Opacity0.8

Current Values:

{}

const schemas = [
  {
    name: 'theme',
    dtype: 'string',
    value: 'light',
    options: ['light', 'dark', 'auto'],
    tags: { grouping: 'Appearance' }
  },
  {
    name: 'quality',
    dtype: 'number',
    value: 2,
    options: [
      { label: 'Low', value: 1 },
      { label: 'Medium', value: 2 },
      { label: 'High', value: 3 },
    ],
    tags: { grouping: 'Appearance' }
  },
  {
    name: 'backgroundColor',
    dtype: 'color',
    value: '#3b82f6',
    tags: { grouping: 'Appearance' }
  },
  {
    name: 'opacity',
    dtype: 'number-slider',
    value: 0.8,
    min: 0,
    max: 1,
    step: 0.1,
    tags: { grouping: 'Appearance' }
  }
];

<DialProvider schemas={schemas} onValueChange={handleValueChange}>
  <DialPanel schemas={schemas} />
</DialProvider>

Advanced Layout Example

Dimensions

Width

Height

Physics

Velocity

Force

const schemas = [
  // Inline label examples
  {
    name: 'width',
    dtype: 'number',
    value: 100,
    min: 0,
    max: 500,
    tags: { grouping: 'Dimensions', labelPosition: 'inline' }
  },
  {
    name: 'height',
    dtype: 'number',
    value: 100,
    min: 0,
    max: 500,
    tags: { grouping: 'Dimensions', labelPosition: 'inline' }
  },
  // Vector with no wrap
  {
    name: 'velocity',
    dtype: 'vector3',
    value: [0, 0, 0],
    min: -100,
    max: 100,
    step: 0.1,
    tags: { grouping: 'Physics', noWrap: true }
  },
  {
    name: 'force',
    dtype: 'vector3',
    value: [0, -9.8, 0],
    min: -50,
    max: 50,
    step: 0.1,
    tags: { grouping: 'Physics', noWrap: true }
  }
];

const groups = [
  { name: 'Dimensions', noWrap: false },
  { name: 'Physics', noWrap: true }
];

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

Basic Input Types

string

Standard text input for string values.

/**
 * @dial-dtype string
 * @dial-icon Text
 */
name: string;

Features:

Single-line text input
Supports placeholder text
Can be used with icons

number

Numeric input with optional constraints and drag-to-adjust functionality.

/**
 * @dial-dtype number
 * @dial-min 0
 * @dial-max 100
 * @dial-step 0.1
 */
value: number;

Features:

Numeric validation
Min/max bounds
Step increment control
Drag to adjust: Click and drag vertically on the input to change values
- Drag up to increase, down to decrease
- Hold Shift for fine control (10x slower)
- Respects min/max constraints
- Maintains step precision
Can also type values directly

number-int

Integer-only numeric input.

/**
 * @dial-dtype number-int
 * @dial-min 0
 * @dial-max 10
 * @dial-step 1
 */
count: number;

Features:

Integer validation
Whole number steps only
Typically rendered as stepper or slider

number-rad

Numeric input for radian values displayed as degrees.

/**
 * @dial-dtype number-rad
 * @dial-step 15  // Step of 15 degrees
 */
angle: number;  // Stored as radians, displayed as degrees

Features:

Single angle input
Value stored internally as radians
Displayed and edited in degrees for user convenience
Automatic degree-to-radian conversion
Useful for single rotation axes

boolean

Toggle switch for boolean values.

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

Features:

Toggle switch UI
Optional icon display
Clear on/off states

Vector Types

vector2

Two-component vector for 2D coordinates.

/**
 * @dial-dtype vector2
 * @dial-min -10
 * @dial-max 10
 * @dial-step 0.1
 */
position2D: [number, number];

Features:

Two numeric inputs (X, Y)
Individual component constraints
Compact horizontal layout

vector3

Three-component vector for 3D coordinates.

/**
 * @dial-dtype vector3
 * @dial-min -100
 * @dial-max 100
 * @dial-step 0.01
 * @dial-icon Move3d
 */
position: [number, number, number];

Features:

Three numeric inputs (X, Y, Z)
Component labels and tooltips
Can be displayed in row or column layout
Per-component min/max/step values

vector4

Four-component vector for quaternions or RGBA values.

/**
 * @dial-dtype vector4
 * @dial-min 0
 * @dial-max 1
 * @dial-step 0.01
 */
quaternion: [number, number, number, number];

Features:

Four numeric inputs
Useful for quaternions, colors with alpha
Compact layout options

Rotation Types

euler

Euler angles for 3D rotation (in degrees).

/**
 * @dial-dtype euler
 * @dial-min -180
 * @dial-max 180
 * @dial-step 1
 * @dial-icon RotateCw
 */
rotation: [number, number, number];

Features:

Three angle inputs (X, Y, Z)
Degree-based input
Circular wrapping (-180 to 180)
Rotation-specific icons

euler-rad

Euler angles stored in radians but displayed in degrees for better UX.

/**
 * @dial-dtype euler-rad
 * @dial-step 15  // Step of 15 degrees
 * @dial-icon RotateCw
 */
rotation: [number, number, number];  // Values stored as radians

Features:

Three angle inputs (X, Y, Z)
Values stored internally as radians
Displayed and edited in degrees for user convenience
Automatic degree-to-radian conversion

quaternion

Quaternion representation for 3D rotation.

/**
 * @dial-dtype quaternion
 */
rotationQuat: [number, number, number, number];

Features:

Four component inputs (X, Y, Z, W)
Normalized values
Advanced rotation representation

Color Types

color

Color picker with various format support.

/**
 * @dial-dtype color
 * @dial-icon Palette
 */
backgroundColor: string;

Features:

Color picker UI
Hex, RGB, HSL support
Alpha channel option
Preset color swatches

rgb

RGB color as three components.

/**
 * @dial-dtype rgb
 * @dial-min 0
 * @dial-max 255
 * @dial-step 1
 */
rgbColor: [number, number, number];

Features:

Three sliders (R, G, B)
0-255 range
Live color preview

Selection Types

select

Dropdown selection from predefined options.

/**
 * @dial-dtype select
 * @dial-options ["option1", "option2", "option3"]
 * @dial-icon List
 */
mode: string;

Features:

Dropdown menu
Predefined options
Single selection
Optional icons for items

enum

Enumerated values with labeled options.

/**
 * @dial-dtype enum
 * @dial-options [
 *   { label: "Small", value: "sm" },
 *   { label: "Medium", value: "md" },
 *   { label: "Large", value: "lg" }
 * ]
 */
size: string;

Features:

Radio buttons or dropdown
Label/value pairs
Type-safe selections

Array Types

array

Dynamic array of values.

/**
 * @dial-dtype array
 * @dial-dtype-element number
 * @dial-min 0
 * @dial-max 100
 */
values: number[];

Features:

Add/remove items
Per-element constraints
Reorderable items
Batch operations

vector

Generic vector with configurable size.

/**
 * @dial-dtype vector
 * @dial-size 6
 * @dial-min -1
 * @dial-max 1
 * @dial-step 0.01
 */
weights: number[];

Features:

Fixed or dynamic size
Uniform constraints
Compact multi-input layout

Special Types

matrix3

3x3 transformation matrix.

/**
 * @dial-dtype matrix3
 */
transform2D: number[][];

Features:

3x3 grid layout
Matrix-specific operations
Visual matrix representation

matrix4

4x4 transformation matrix.

/**
 * @dial-dtype matrix4
 */
transform3D: number[][];

Features:

4x4 grid layout
Homogeneous coordinates
3D transformation support

json

JSON object editor.

/**
 * @dial-dtype json
 * @dial-icon Code
 */
config: object;

Features:

Syntax-highlighted editor
JSON validation
Tree view option
Schema validation support

file

File path or file upload.

/**
 * @dial-dtype file
 * @dial-accept ".jpg,.png,.gif"
 * @dial-icon FileImage
 */
imagePath: string;

Features:

File picker dialog
Drag and drop support
File type filtering
Path or base64 output

Layout Modifiers

Column Layout

Display vector inputs in columns.

/**
 * @dial-dtype vector3
 * @dial-col-3
 */
dimensions: [number, number, number];

Row Layout

Display inputs horizontally.

/**
 * @dial-dtype vector2
 * @dial-row
 */
coordinates: [number, number];

No Wrap

Prevent line wrapping for grouped inputs.

/**
 * @dial transform @dial-no-wrap
 */

Label Position

Control label placement.

/**
 * @dial-dtype number
 * @dial-label-inline
 */
opacity: number;

Type-Specific Annotations

Numeric Constraints

@dial-min <number>      // Minimum value
@dial-max <number>      // Maximum value
@dial-step <number>     // Step increment
@dial-precision <int>   // Decimal places

Vector Constraints

@dial-mins [<number>, ...]   // Per-component minimums
@dial-maxs [<number>, ...]   // Per-component maximums
@dial-steps [<number>, ...]  // Per-component steps
@dial-placeholders [<string>, ...]  // Component labels

Selection Options

@dial-options [...]     // Array of options
@dial-default <value>   // Default selection
@dial-multiple         // Allow multiple selections

Display Options

@dial-icon <name>      // Lucide icon name
@dial-tooltip <text>   // Hover tooltip
@dial-placeholder <text> // Input placeholder
@dial-disabled        // Disable input
@dial-readonly        // Read-only mode

Best Practices

Choose the right type: Use specific types like vector3 instead of generic array for better UI.
Set appropriate constraints: Always define min/max/step for numeric inputs.
Group related properties: Use @dial <group> to organize related controls.
Use semantic icons: Choose icons that represent the property's purpose.
Provide tooltips: Add helpful descriptions for complex properties.
Consider layout: Use row/column modifiers for better space utilization.

Examples

Complete 3D Object Properties

interface Object3DProps {
  /** @dial transform @dial-dtype vector3 @dial-icon Move3d */
  position: [number, number, number];

  /** @dial transform @dial-dtype euler @dial-icon RotateCw */
  rotation: [number, number, number];

  /** @dial transform @dial-dtype vector3 @dial-min 0.01 @dial-icon Scaling */
  scale: [number, number, number];

  /** @dial appearance @dial-dtype color @dial-icon Palette */
  color: string;

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

  /** @dial visibility @dial-dtype boolean @dial-icon Eye */
  visible: boolean;
}

Material Properties

interface MaterialProps {
  /** @dial appearance @dial-dtype color */
  diffuseColor: string;

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

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

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

  /** @dial textures @dial-dtype file @dial-accept ".jpg,.png" */
  diffuseMap: string;

  /** @dial textures @dial-dtype file @dial-accept ".jpg,.png" */
  normalMap: string;
}

Next Steps

Learn about the Dial Annotation Syntax
Follow the Tutorial to implement Dial in your project
See Controlled Dials for programmatic control
Check API Notes for detailed API reference