Playground Controls

Controls allow users to interactively modify component properties in the playground. They’re defined in component.json under playground.controls.

Control Types

text

Text input for string values.

{
  "label": {
    "type": "text",
    "label": "Label",
    "defaultValue": "Button",
    "placeholder": "Enter label..."
  }
}

Option	Type	Description
label	string	Display label
defaultValue	string	Initial value
placeholder	string	Placeholder text

number

Numeric input with optional min/max/step.

{
  "count": {
    "type": "number",
    "label": "Count",
    "defaultValue": 5,
    "min": 0,
    "max": 100,
    "step": 1
  }
}

Option	Type	Description
label	string	Display label
defaultValue	number	Initial value
min	number	Minimum value
max	number	Maximum value
step	number	Increment step

boolean

Checkbox for true/false values.

{
  "disabled": {
    "type": "boolean",
    "label": "Disabled",
    "defaultValue": false
  }
}

Option	Type	Description
label	string	Display label
defaultValue	boolean	Initial value

select

Dropdown for selecting from options.

{
  "variant": {
    "type": "select",
    "label": "Variant",
    "defaultValue": "primary",
    "options": ["primary", "secondary", "danger"]
  }
}

With custom labels:

{
  "size": {
    "type": "select",
    "label": "Size",
    "defaultValue": "md",
    "options": [
      { "label": "Small", "value": "sm" },
      { "label": "Medium", "value": "md" },
      { "label": "Large", "value": "lg" }
    ]
  }
}

Option	Type	Description
label	string	Display label
defaultValue	string	Initial value
options	array	String values or {label, value} objects

radio

Radio buttons for mutually exclusive options.

{
  "alignment": {
    "type": "radio",
    "label": "Alignment",
    "defaultValue": "left",
    "options": ["left", "center", "right"]
  }
}

Option	Type	Description
label	string	Display label
defaultValue	string	Initial value
options	array	String values or {label, value} objects

color

Color picker input.

{
  "accentColor": {
    "type": "color",
    "label": "Accent Color",
    "defaultValue": "#3b82f6"
  }
}

Option	Type	Description
label	string	Display label
defaultValue	string	Initial hex color

range

Slider for numeric ranges.

{
  "opacity": {
    "type": "range",
    "label": "Opacity",
    "defaultValue": 100,
    "min": 0,
    "max": 100,
    "step": 5
  }
}

Option	Type	Description
label	string	Display label
defaultValue	number	Initial value
min	number	Minimum value (required)
max	number	Maximum value (required)
step	number	Increment step

json

JSON editor for complex objects/arrays.

{
  "items": {
    "type": "json",
    "label": "Items",
    "defaultValue": [
      { "id": 1, "name": "Item 1" },
      { "id": 2, "name": "Item 2" }
    ]
  }
}

Option	Type	Description
label	string	Display label
defaultValue	any	Initial JSON value

Complete Example

{
  "id": "button",
  "title": "Button",
  "status": "stable",
  "kind": "standalone",
  "exports": {
    "customElement": "my-button"
  },
  "playground": {
    "primaryScenarioId": "button-default",
    "controls": {
      "variant": {
        "type": "select",
        "label": "Variant",
        "defaultValue": "primary",
        "options": [
          { "label": "Primary", "value": "primary" },
          { "label": "Secondary", "value": "secondary" },
          { "label": "Outline", "value": "outline" },
          { "label": "Danger", "value": "danger" }
        ]
      },
      "size": {
        "type": "radio",
        "label": "Size",
        "defaultValue": "medium",
        "options": ["small", "medium", "large"]
      },
      "disabled": {
        "type": "boolean",
        "label": "Disabled",
        "defaultValue": false
      },
      "loading": {
        "type": "boolean",
        "label": "Loading",
        "defaultValue": false
      },
      "width": {
        "type": "range",
        "label": "Min Width",
        "defaultValue": 100,
        "min": 50,
        "max": 300,
        "step": 10
      }
    }
  }
}

How Controls Work

1. Attributes vs Properties
   • Most controls update HTML attributes via setAttribute()
   • json controls update DOM properties directly
2. HTML Code Generation
   • Simple values generate attribute strings
   • Complex values (from json) generate a <script> tag
3. Live Updates
   • Changes immediately reflect in the preview
   • The HTML code panel updates in real-time

Best Practices

1. Provide Defaults - Always set defaultValue for predictable behavior
2. Use Descriptive Labels - Clear labels improve usability
3. Limit Options - Too many options can overwhelm users
4. Group Related Controls - Order controls logically in your JSON
5. Match Types - Use appropriate control types for each property

Next Steps

• Learn about categorization
• Set up visual testing