Leva Documentation

The Spring Plugin provides an editor for spring physics configurations, allowing you to adjust tension, friction, and mass.

npm i @leva-ui/plugin-spring

import { useControls } from 'leva'
import { spring } from '@leva-ui/plugin-spring'

function MyComponent() {
  const { mySpring } = useControls({
    mySpring: spring({
      tension: 100,
      friction: 30,
      mass: 1,
    }),
  })

  // Returns a spring configuration object
  return <div>{mySpring.toString()}</div>
}

Inputs configured with optional: true or disabled: true will have their return type include undefined.

By default, inputs with an onChange handler are considered 'transient' and are not returned in the useControls object. To ensure the value is returned while still using onChange, set transient: false.

// Optional/Disabled return undefined
const { optionalValue } = useControls({
  optionalValue: {
    value: 'hello',
    optional: true,
  },
})
// optionalValue: string | undefined

// Transient vs Non-transient
const { color } = useControls({
  color: {
    value: '#f00',
    onChange: (v) => console.log(v),
    transient: false, // Set to false to ensure 'color' is returned in the object
  },
})
// color: string

To completely hide the GUI (for example, based on user preferences), set the hidden prop to true on the <Leva> component. Note that useControls hooks will still function, but their UI will not be rendered.

import { Leva } from 'leva'

function MyApp() {
  return (
    <>
      <Leva hidden={true} />
    </>
  )
    </>
  )
}

To use Leva's state management without the default HTML UI, install the leva package.

npm install leva
# or
yarn add leva

To use the Bezier plugin with Leva, install the package via npm:

npm i @leva-ui/plugin-bezier

The Plot Plugin is a mathematical function plotter and evaluator. It allows you to define an expression and set bounds for the X and Y axes.

npm i @leva-ui/plugin-plot

import { useControls } from 'leva'
import { plot } from '@leva-ui/plugin-plot'

function MyComponent() {
  const { y } = useControls({
    y: plot({
      expression: 'cos(x)',
      graph: true,
      boundsX: [-10, 10],
      boundsY: [0, 100],
    }),
  })

  // Evaluate the function at a point
  const result = y(Math.PI)

  return <div>cos(π) = {result}</div>
}

Leva provides full type inference for control values. You can rely on automatic inference from your schema or explicitly define a schema using the Schema type for better type safety.

import { useControls, Schema } from 'leva'

// Option 1: Automatic inference
const { count, name } = useControls({
  count: 0,
  name: 'Hello',
})

// Option 2: Explicitly typed schema
type MySchema = {
  count: number
  name: string
  enabled: boolean
}

const values = useControls<MySchema>({
  count: 0,
  name: 'Hello',
  enabled: true,
})

To use Leva, import useControls and the Leva component. The Leva component should be rendered once in your application (e.g., at the root) to display the GUI panel. Controls are added to the GUI automatically when the component using useControls is mounted. The order of controls in the GUI follows the order of hook calls.

import { useControls, Leva } from 'leva'

function MyComponent() {
  const { myValue } = useControls({ myValue: 10 })
  return myValue
}

function MyApp() {
  return (
    <>
      <Leva />
      <MyComponent />
    </>
  )
}

Folders and complex input options (like min/max/step) maintain type safety. For select inputs, use as const to provide better autocomplete for specific string literal types.

import { folder, useControls } from 'leva'

// Folders
const values = useControls({
  position: folder({
    x: 0,
    y: 0,
  }),
})
// values.position.x is typed as number

// Select inputs with autocomplete
type Preset = 'low' | 'medium' | 'high'

const { preset } = useControls({
  preset: {
    value: 'medium' as Preset,
    options: ['low', 'medium', 'high'] as const,
  },
})

To use the Leva Plot plugin, install the package via npm:

npm i @leva-ui/plugin-plot