TiltPad
A small pad for tilting something in 3D: drag the knob or use the arrow keys.
import { TiltPad } from "@butteryui/react";Demo
When to use it
Use it for
- Tilting a picture on a slide in 3D, as x and y from −1 to 1 mapped to rotateY and rotateX
Not for
- Turning something flat: use a Slider in degrees
- Placing something: use AnchorGrid
Examples
Locked tilt
A disabled pad: the tilt holds while it's locked, dimmed and ignoring drags and keys, and moves once it's unlocked.
Picture tilt
A tilt mapped to a picture's 3D transform: ±20° each way at 1200px of perspective.
Placement section
An inspector's placement section: a tilt row with its value and a chip that lays it flat, over a turn slider, and Reset for both.
Placement
Tilt with reset
A tilt pad paired with a chip that lays it flat, quiet but still focusable once it is.
Variants and states
Tilt with a chip that lays it flat
Drag the knob or use the arrow keys; the accent arc shows the direction. Flat glides back on spring.smooth.
Level and disabled
Props
TiltPad
| Prop | Type | Default | Description |
|---|---|---|---|
labelrequired | string | What is tilted, such as "Tilt". It names the control. | |
value | TiltValue | The tilt. Pair with onValueChange to control it. | |
defaultValue | TiltValue | The tilt at first when uncontrolled. Defaults to level. | |
onValueChange | ((value: TiltValue) => void) | Called with each change: every frame of a drag, each key press, each reset. | |
onValueCommit | ((value: TiltValue) => void) | Called when a drag ends or a key changes the tilt, with the tilt it settled on. | |
step | number | 0.1 | How far one arrow key press tilts, from 0 to 1. Shift tilts five times as far. Defaults to 0.1. |
disabled | boolean | Keeps it from changing. | |
labels | Partial<TiltPadLabels> | Words to use instead of the English ones. |
It also takes Omit<ComponentPropsWithRef<"div">, "defaultValue" | "onChange" | "children">.
TiltValue
How far something is tilted: `x` to the right and `y` downwards, each from −1 to 1.
| Field | Type | Default | Description |
|---|---|---|---|
xrequired | number | Tilt to the right (positive) or left (negative), from −1 to 1. | |
yrequired | number | Tilt downwards (positive) or upwards (negative), from −1 to 1. |
TiltPadLabels
The words a `TiltPad` reads out, for other languages.
| Field | Type | Default | Description |
|---|---|---|---|
xrequired | string | Names the sideways control. | |
yrequired | string | Names the up-and-down control. | |
hintrequired | string | Says how to use it with the keyboard. | |
leftrequired | string | Said after a tilt to the left, as in "30% left". | |
rightrequired | string | Said after a tilt to the right. | |
uprequired | string | Said after an upward tilt. | |
downrequired | string | Said after a downward tilt. | |
levelrequired | string | Said for no tilt on an axis. |
Accessibility
A group named by label holding two sliders, "Left and right" and "Up and down", each reading its value as words ("30% right"). Left and right arrows tilt sideways, up and down tilt up and down (focus moves to that slider so its value is read), Shift takes bigger steps, and Backspace, Delete or Home set it level. The pad shows the focus ring.
| Keys | What they do |
|---|---|
| Tab | Moves to the pad, one stop on the axis last moved, and on out of it |
| Arrow Left or Arrow Right | Tilts it left or right by step, 0.1 by default |
| Arrow Up or Arrow Down | Tilts it up or down by step |
| Shift and an arrow | Tilts it five steps at once |
| Page Up or Page Down | Tilts it five steps right or left, or up or down, along the axis last moved |
| Backspace, Delete or Home | Sets it level |
Motion
Its selection indicator slides to the chosen option on `spring.snappy`, inside one track.
With reduced motion: The knob jumps to a new tilt at once instead of gliding there; a drag follows the pointer as it always does.
Layout
A 32px circle that keeps its size wherever it sits, its 24px knob travelling 4px each way inside it. The whole circle is the hit area for a drag, and it shows no text.