Keyframery

Preferences

Puts people's choices on data attributes for your CSS, with a switcher whose key stretches to the value and the four motion styles ready-made.

See it as an AI agent does.

Resize preview. Focus the handle and use the left or right arrow keys. Hold Shift for larger steps.— px
Customize1 controls
Animation speed1×

Installation

npx shadcn@latest add @keyframery/preferences

This adds components/keyframery/preferences.tsx and its primitive to your project, and installs UI SDK, along with segmented-control, which it builds on. The motion tokens are added to your global CSS the first time you install a component.

Usage

import { createLocalStorage, createPreference } from "@ui-sdk/core"

import { Preferences, PreferenceSwitcher } from "@/components/keyframery/preferences"

const view = createPreference({
  values: ["list", "grid"],
  defaultValue: "list",
  attribute: "data-view",
  storage: createLocalStorage("files-view"),
})

export default function Usage() {
  return (
    <Preferences preferences={[view]}>
      <PreferenceSwitcher preference={view} aria-label="View" />
      <ul className="grid gap-2 in-data-[view=grid]:grid-cols-2">
        <li>Q3 roadmap.pdf</li>
        <li>Launch checklist.md</li>
      </ul>
    </Preferences>
  )
}

Examples

A saved choice

The text size goes on a data-size attribute and the paragraph styles by it. Storage keeps the choice, so it is still there after a reload.

Read the value

usePreference gives a component the current value, so it can render differently, not only restyle.

Motion style

Keyframery's own preference. The switcher sets the motion style for the whole page and remembers it, and every Keyframery component follows.

Motion

MoveWhat you see
StretchA preference switcher's key stretches to the value you pick, as the motion style switcher's does between the four styles.

Timing and springiness follow the motion style you set. To change how fast this preferences moves, pass speed:

<PreferenceSwitcher preference={view} speed="fast" />

"fast" is 0.6×, "slow" 1.4×, and a number sets the multiplier. With reduced motion turned on, nothing moves: changes happen at once or with a short fade.

Theming

Set these CSS variables on the component or a parent. Leave them unset to follow the light and dark theme. The open Customize panel below the preview lets you try these settings.

VariableWhat it changesDefault
--preferences-trackSwitcher well--muted
--preferences-keySelected key--background, --accent in dark
--preferences-inkUnselected text--muted-foreground
--preferences-selected-inkSelected text--foreground
--preferences-heightOption height2rem
--preferences-radiusWell corners12px
--preferences-key-radiusOption corners9px
--preferences-gapOption gap0.125rem

API reference

Every part takes className and children. Parts from UI SDK also take render, to draw your own element, and a function of their state for className and style. Props not listed here are in the UI SDK preferences reference.

PreferenceSwitcher

Renders a <div>, and takes its props too.

Prop

Type

MotionStyle

Renders a <div>, and takes its props too.

Prop

Type

Preferences

Renders a <div>, and takes its props too.

Prop

Type

MotionStyleSwitcher

Renders a <div>, and takes its props too.

Prop

Type

Hooks

usePreference

Call it inside the component to read and change its state.

Keyboard

KeyWhat it does
← →In a preference switcher, moves to the previous or next value.

Accessibility

Keyboard, focus and screen-reader behaviour come from UI SDK and are not changed. More in Accessibility.

Swap the import

Already using UI SDK's preferences with your own styles? Keep your markup and change one line. The primitive adds motion and nothing else.

// Before
import { … } from "@ui-sdk/react/preferences"

// After: same parts, same props, now animated
import { … } from "@/components/keyframery/primitives/preferences"

Questions

How does the animated Preferences for UI SDK move?

Stretch: A preference switcher's key stretches to the value you pick, as the motion style switcher's does between the four styles.

Do I need Motion or Framer Motion for the animated Preferences?

No. Every move is plain CSS, so there is nothing to install besides the component and UI SDK.

Can I keep my own styling and only take the motion?

Yes. Import from @/components/keyframery/primitives/preferences instead. It has the same parts and props as @ui-sdk/react/preferences and adds motion only.

What happens to the Preferences when someone turns on reduced motion?

Nothing moves. State changes happen at once, or with a short fade.

All components

On this page