| title | Inputs |
|---|---|
| description | |
| nav | 0 |
leva will check the input settings and provide the best possible component.
A single numerical input.
const { myNumber } = useControls({
myNumber: 4,
})- Increase / decrease numbers with arrow keys, with alt (±0.1) and shift (±10) modifiers support.
- Change the value by either dragging over the input label or the inner label.
- Automatically filters the input to be a numerical value
- Automatically calculates the number input step based on the initial value magnitude and significant digits.
A Number input with an additional range slider. It will be used when you provide a min and max value.
const { myNumber } = useControls({
myNumber: {
value: 4,
min: 0,
max: 10,
step: 1,
},
})All rules from Number type also apply.
A color picker. Color format is inferred by the object used:
const colors = useControls({
myFooColor: '#fff',
myBarColor: { r: 200, b: 125, g: 106, a: 0.4 },
})In the example, myFooColor will create an Hexadecimal field while myBarColor will expose return 4 values in separate r, g, b and a numerical fields.
A simple toggle.
const { toggle } = useControls({ toggle: true })A text input field. Can be configured as a single-line input or multi-line textarea.
const { myString } = useControls({
myString: 'Hello World',
})Enable multi-line editing with rows: true for default height, or specify a number:
const { description } = useControls({
description: {
value: 'Multi-line\ntext\ncontent',
rows: true, // Default height
},
notes: {
value: 'Custom height',
rows: 5, // 5 rows tall
},
})Make strings read-only while still allowing display:
const { status } = useControls({
status: {
value: 'This text cannot be edited',
editable: false,
},
})An array containing two numerical values.
Will be used when value is an array of 2 numbers and min and max are specified.
const { myInterval } = useControls({
myInterval: {
min: 0,
max: 10,
// initial value of 4, 5
value: [4, 5],
},
})All rules from Number type also apply.
A dropdown select input with a specified list of elements. An optional default value can be provided.
const { color } = useControls({
color: {
options: ['red', 'green', 'blue', 'yellow'],
value: 'red',
},
})You can also use objects for labeled options:
const { preset } = useControls({
preset: {
options: {
low: 'Low Quality',
medium: 'Medium Quality',
high: 'High Quality',
},
value: 'medium',
},
})An image input that allows uploading or selecting an image file. Returns the image URL or undefined.
const { myImage } = useControls({
myImage: { image: undefined },
})The returned value will be a data URL string when an image is selected, or undefined when no image is set.
Compound input of two numerical values without min and max bounds.
Will be used when value is an object with x and y properties or an array of
two numbers.
const { position } = useControls({
position: { x: 0, y: 0 },
boxSize: [10, 20],
})The joystick can be hidden with joystick: false and inverted with "invertY".
const { position } = useControls({
position: {
value: { x: 0, y: 0 },
joystick: 'invertY',
},
boxSize: {
value: [10, 20],
joystick: false,
},
})The step setting can be used to change joystick's resistance.
const { position } = useControls({
position: {
value: { x: 0, y: 0 },
step: 0.1,
},
})You can also use your keyboard to control the step. Pressing the shift key while dragging increases the step. Pressing alt decreases the step.
You can set options separately for each coordinate by nesting them under coordinate's key.
useControls({
vec2: {
value: {
x: 0,
y: 0,
},
x: {
step: 0.1,
},
y: {
step: 1,
},
},
})Very similar to Vector2 but now with the z axis.
useControls({
vec3: {
x: 0,
y: 2,
z: 1.5,
},
anotherVec3: [3, 1, 1],
})One difference with Vector2 to keep in mind is that you don't have the joystick option.
Both Vector2 and Vector3 support a lock option that synchronizes all coordinates when one is changed:
const { position } = useControls({
position: {
value: [1, 1, 1],
lock: true, // Changing x will also update y and z
},
})All inputs support common options:
Customize the display label:
const { color } = useControls({
color: {
value: '#f00',
label: 'Background Color',
},
})You can also use React elements as labels:
import { Half2Icon } from '@radix-ui/react-icons'
const { color } = useControls({
color: {
value: '#f00',
label: <Half2Icon />,
},
})Add a tooltip or help text:
const { position } = useControls({
position: {
value: [0, 0, 0],
hint: 'Position of the object relative to the screen',
},
})Conditionally show inputs based on other values:
const { showAdvanced, advancedValue } = useControls({
showAdvanced: false,
advancedValue: {
value: 0,
render: (get) => get('showAdvanced'),
},
})Control the display order of inputs:
const values = useControls({
last: { value: 0, order: 1 },
middle: { value: 0, order: -1 },
first: { value: 0, order: -2 },
})Lower order values appear first.
Mark inputs as optional (they can be hidden/shown via UI):
const { color } = useControls({
color: {
value: '#f00',
optional: true,
},
})Disable inputs (they won't be editable):
const { readonly } = useControls({
readonly: {
value: 'Cannot edit',
disabled: true,
hint: 'This input is disabled',
},
})Execute a callback when the value changes (see Controlled Inputs):
const values = useControls({
color: {
value: '#f00',
onChange: (value) => {
console.log('Color changed:', value)
},
},
})Callbacks for when editing begins/ends:
const values = useControls({
position: {
value: { x: 0, y: 0 },
onEditStart: (value, path) => {
console.log('Started editing', path)
},
onEditEnd: (value, path) => {
console.log('Finished editing', path)
},
},
})Force a specific input type even if Leva would infer differently:
import { LevaInputs } from 'leva'
const { value } = useControls({
value: {
type: LevaInputs.STRING,
value: '#f00', // Would normally be a color, but forced to string
},
})