Skip to contentKino
Skip to Content

Preferences

A person's preferences, such as light or dark, density or reduced motion, saved on their device and written as data attributes before the first paint, so a saved choice never flashes the default.

npx shadcn add https://kinoui.com/r/preferences.json
Share on

Examples

Appearance

Saved on this device, for every workspace.
ThemeLight, dark, or the same as your device.
DensityHow much room lists and controls take.
FeelHow panels open and highlights travel.
CornersControls as rounded boxes, or as pills.
KN-412
Export the March invoices as one PDF
MC
KN-409
Sign-in link expires before the email arrives
PR
KN-401
Add Danish to the invoice languages
TA

Appearance settings

Put <Preferences> at the top of the page with the ready-made colour scheme, density, feel, shape and motion preferences, and bind each control to usePreference. Here the card keeps its own, so the rest of the page stays as it is.

Projects

Checkout v2
24 openMC
Invoice languages
9 openTA
Sign-in links
13 openPR
Annual pricing
6 openJL

Your own preference

Make one with createPreference and style what it wraps by its attribute, here a list or a grid that stays as it was left.

Installation

npx shadcn@latest add https://kinoui.com/r/preferences.json
Files
components/kino/preferences.tsx

New to Kino? Installation covers what your project needs first and the @kino namespace.

API reference

Preferences

PropTypeDefaultDescription
preferencesPreference[]NoneWhat it applies. Keep the list the same for the life of the page, and put it high in the page: its script runs before the first paint.
noncestringNoneYour Content Security Policy’s nonce, for the inline script.
childrenReactNodeNoneWhat the preferences that aren’t global apply to.

usePreference

PropTypeDefaultDescription
preferencePreferenceNoneReads it anywhere, with no provider. Returns { value, resolved, setValue }: what the person chose, such as system; what applies now, such as dark; and the function that saves a new choice. Until the page hydrates it returns the default, and a control bound to it takes the saved value in place.

createPreference

PropTypeDefaultDescription
attribute`data-${string}`NoneThe attribute CSS reads, such as data-view.
valuesreadonly string[]NoneEvery value it takes. A saved value outside the list is ignored.
defaultValuestringNoneWhat applies until one is picked.
storageKeystringnullthe attribute without `data-`The localStorage key it is saved under; null keeps it for this visit.
globalbooleanfalseOn <html>, for the whole page and the popups portalled to it, rather than on what <Preferences> wraps.
system{ query, matches, otherwise }NoneWhat a system value follows: a media query, and the value written while it matches and while it doesn’t. It follows the device live.

Data attributes

AttributeOnDescription
data-color-scheme<html>colorSchemePreference: light or dark, with system already resolved. It also writes the dark or light class shadcn’s theme reads, and color-scheme. It is saved under theme with next-themes’ values, so moving from next-themes keeps every visitor’s choice; use one or the other.
data-density<html>densityPreference: snug, balanced or airy, as Density (opens in a new tab) reads it.
data-feel<html>feelPreference: calm, crisp or lively, as the feel (opens in a new tab) reads it.
data-shape<html>shapePreference: standard or round, as Shape (opens in a new tab) reads it.
data-motion<html>motionPreference: reduce or full, with system already resolved. The item’s CSS makes Tailwind’s motion-reduce: and motion-safe: answer data-motion="reduce" as well as the device’s setting.

Accessibility

  • Reduce motion only adds to what the device asks: while the device asks for less motion, the setting is on and can’t be turned off, and its control says why.
  • A changed colour scheme switches every colour at once, with no fade, while a press or a highlight in motion finishes.
  • A saved choice is on the page before it paints, so a dark theme never flashes light and a control never slides to its saved value on load.
  • useMotionTransition reads data-motion on <html>; a nested data-motion="reduce" reduces CSS only.