aporia

A tiny floating panel of sliders and LFO's for whatever you're making. Hook it up to your tools, let values animate by themselves, or just play around until things feel right.

Install

npm i aporia

import 'aporia/styles.css'

Import the stylesheet once in your app entry. The panel floats and positions itself, so it doesn't need a container.

Quick start

import { useState } from 'react'
import Panel, { Category, SliderRow, ColorRow, ToggleRow } from 'aporia'
import 'aporia/styles.css'

export default function App() {
  const [size, setSize] = useState(40)
  const [color, setColor] = useState('#E8470C')
  const [enabled, setEnabled] = useState(true)

  return (
    <Panel>
      <Category title="Basics">
        <SliderRow label="Size" value={size} min={0} max={100} onChange={setSize} />
        <ColorRow label="Color" value={color} onChange={setColor} />
        <ToggleRow label="Enabled" checked={enabled} onChange={setEnabled} />
      </Category>
    </Panel>
  )
}

Rows live inside a Category, categories inside a Panel. Every row is controlled: you keep the value in your own state and write it back in onChange.

Numbers and colors can also be driven, animated by an LFO instead of by hand. That takes an id on the row and a DriverProvider around your app; see Driving a value.

Driving a value

A driver makes a value move on its own. You stop setting the number and start setting how it moves: a shape, a rate, and how far it swings.

Wrap your app in DriverProvider. Then two things connect a slider to its moving value: a matching id, and useDriven.

import { useState } from 'react'
import Panel, { Category, SliderRow, DriverProvider, useDriven } from 'aporia'

function Pattern() {
  const [density, setDensity] = useState(40)
  const liveDensity = useDriven('density', density)

  return (
    <>
      <canvas ref={draw(liveDensity)} />
      <Panel>
        <Category title="Pattern">
          <SliderRow id="density" label="Density" value={density} min={0} max={100} onChange={setDensity} />
        </Category>
      </Panel>
    </>
  )
}

export default function App() {
  return (
    <DriverProvider>
      <Pattern />
    </DriverProvider>
  )
}

The id on the row and the string in useDriven are the same name. That's what connects them.

useDriven gives you the moving number while a driver runs, and your own state when none does. So render from it, leave value and onChange as they were, and call it in the component that actually uses the value. It re-renders that component while a driver runs.

Shapes: sin, triangle, ramp, pulse, noise.

A row with an id gets a small dot that opens the generator editor. Grabbing the control hands the value back to you and pauses the driver; letting go picks it up where it was. You can also start one from code with defaultDriver={{ kind: 'sin', rate: 0.25, amplitude: 0.35, center: 0.5 }}.

A PointRow drives each axis on its own, as origin.x and origin.y; read both with useDrivenPoint('origin', origin). A ColorRow drives perceptual hue as bg.h while preserving the color's lightness and chroma; useDrivenColor('bg', bg) gives you the live hex.

Without a provider, useDriven just returns the fallback, so a static app keeps working.

Already animating something?

Aporia runs a clock only because most tools don't have one. If you already have a render loop, give it yours instead: feed time with useDriverClock().tick(t) and read values with getValue(id) in the same loop. Nothing re-renders, and your visual and the panel land on the same frame. Two loops drift; one can't.

function Scene() {
  const { tick, getValue } = useDriverClock()

  useFrame(({ clock }) => {
    tick(clock.elapsedTime)
    mesh.scale.setScalar(getValue('size') ?? size)
  })
}

getValue returns undefined when nothing is driving that id, hence the fallback. The first tick you call permanently stops Aporia's internal clock, so two clocks never run at once.

Presets

Save and restore sets of values. You stay in control of your state: usePresets snapshots the values you give it and applies them back. Pass a storageKey to persist to localStorage.

const presets = usePresets({
  values: { size, color },
  onApply: (v) => { setSize(v.size); setColor(v.color) },
  storageKey: 'my-tool',
})

<Category title="Presets">
  <PresetRow presets={presets} />
</Category>

Controls

| Row | For | | --- | --- | | SliderRow | A number with a low and a high end. Pass fmt to dress up the display, scale="log" for rates and sizes. | | NumberRow | A number on a scrubbable ribbon, or typed. Bounds optional. | | PointRow | Two numbers as a point on a pad. Driven per axis. | | TextRow | A string. | | ColorRow | A color, in and out as a hex string. Its perceptual hue can be driven. | | GradientRow | A gradient, with parseGradient / stopsToGradient to read and write CSS. | | SelectRow | One of a set of options. | | ToggleRow | On or off. | | ButtonRow | An action. | | PresetRow | Save and load named sets of values. |

SliderRow, NumberRow, PointRow and ColorRow can be driven.

For agents

If you're an AI agent adding Aporia to someone's app:

• "Drivable" means a row's value can be animated by a driver (an LFO). SliderRow, NumberRow, PointRow and ColorRow are drivable. It takes three things: an id on the row, a DriverProvider above it, and rendering from useDriven(id, value) instead of value. See Driving a value.
• When you add a drivable row, wire it up that way from the start, so it can be driven from the panel without another change.
• Labels are plain text. Don't add icons to ButtonRow or any other row.
• Every prop and hook is documented in the shipped types: dist/index.d.ts, and dist/drivers/DriverProvider.d.ts for driving.

Notes

• Dark theme by default.
• Peer deps: react, react-dom, motion, @base-ui/react.

License

MIT