1. [Home](/)
1. [Dial](/dial)
1. Controlled Dials

# Controlled Dials


The `DialProvider` component supports both controlled and uncontrolled modes, giving you flexibility in how you manage dial state.


## Simple 3D Object Example


transformPositionxyzRenderOrderResetExamplePosition: [0.0, 5.0, 0.0]Render Order: 0```jsx
const schemas = [
  {
    name: "position",
    dtype: "vector3",
    value: [1, 2, 3],
    //...
  }
];

const [values, setValues] = useState({
  position: [0, 5, 0],
  renderOrder: 0
});


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

return (
  <DialProvider
    schemas={schemas}
    values={values}
    onValueChange={handleChange}
  >
    <DialPanel schemas={schemas} />
  </DialProvider>
);

```


## Full Schema Example from JSON


FooBar Object PropertiestransformPositionxyzRotationxyzScalexyzdisplayVisibleOpacityReset All```
{
  "position": [
    0,
    5,
    0
  ],
  "rotation": [
    0,
    0,
    0
  ],
  "scale": [
    1,
    1,
    1
  ],
  "visible": true,
  "opacity": 1
}
```

```jsx
// Schema data structure (could be loaded from JSON)
const schemaData = {
  "FooBar": {
    "schemas": [
      {
        "name": "position",
        "dtype": "vector3",
        "value": [0, 5, 0],
        "min": -10,
        "max": 10,
        "step": 0.1,
        "tags": {
          "grouping": "transform",
          "noWrap": true
        }
      },
      // ... more schemas
    ]
  }
};

// Initialize values from schemas
const [values, setValues] = useState(() => {
  const initial = {};
  schemaData.FooBar.schemas.forEach(schema => {
    initial[schema.name] = schema.value;
  });
  return initial;
});

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

return (
  <DialProvider
    schemas={schemaData.FooBar.schemas}
    values={values}
    onValueChange={handleChange}
  >
    <DialPanel schemas={schemaData.FooBar.schemas} />
  </DialProvider>
);

```


## API Reference


### DialProvider Props


| Prop | Type | Description | 
| `schemas` | `DialSchema[]` | Array of dial schemas defining the dials | 
| `values` | `Record<string, DialValue>` | Current values for controlled mode | 
| `initialValues` | `Record<string, DialValue>` | Initial values for uncontrolled mode | 
| `onValueChange` | `(name: string, value: DialValue) => void` | Callback when values change | 
| `children` | `ReactNode` | Child components | 



### Schema Structure


```typescript
interface DialSchema {
  name: string;           // Unique identifier
  dtype: string;          // "number", "boolean", "vector3", "select", etc.
  value?: any;           // Default value
  min?: number;          // For number/vector inputs
  max?: number;          // For number/vector inputs
  step?: number;         // Step size for number/vector inputs
  options?: string[];    // For select inputs
  tags?: {
    grouping?: string;    // Group related controls
    noWrap?: boolean;     // Prevent wrapping in group
    // ... other tags
  };
}

```


### Common Data Types



- **`number`**: Single numeric value

- **`boolean`**: True/false toggle

- **`vector3`**: 3D vector [x, y, z]

- **`select`**: Dropdown with options

- **`string`**: Text input



### Grouping with Tags


The `tags.grouping` property allows you to organize related controls together. Controls with the same `grouping` value will be visually grouped in the UI.


```json
{
  "tags": {
    "grouping": "transform",
    "noWrap": true
  }
}

```