Appearance pickers

Code

import { ReadingSettings, ThemeGallery, readingStyleVars, type ReadingPreferences } from "@fadymondy/nasaq/web";import { useState } from "react";const themes = [  { id: "paper", label: "Paper", mode: "light" as const, swatches: ["var(--nq-surface)", "var(--nq-surface-soft)", "var(--nq-fg)", "var(--nq-brand)"] },  { id: "ink", label: "Ink", mode: "dark" as const, swatches: ["var(--nq-fg)", "var(--nq-fg-muted)", "var(--nq-surface)", "var(--nq-brand)"] },];export function Appearance() {  const [theme, setTheme] = useState("paper");  const [reading, setReading] = useState<ReadingPreferences>({ fontSize: "md", width: "normal", spacing: "normal" });  return (    <div className="flex flex-col gap-8">      <ThemeGallery themes={themes} value={theme} onValueChange={setTheme} />      <ReadingSettings value={reading} onValueChange={setReading} />      <article style={readingStyleVars(reading)}>{/* uses var(--reading-scale) etc. */}</article>    </div>  );}

Pickers · beta

Live examples and controls: Appearance pickers in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/appearance-pickers.json

Three pickers for the "Appearance" page of a settings screen.

They only hold the choice and report it. Applying it (setting a class, a CSS variable, a background) and saving it is your code, so the same pickers work in a web app, a desktop shell and an extension.

When to useCopy Anchor Link

• A product with several named themes beyond light and dark.
• Reading-heavy products (articles, documents, notes) where comfort settings matter.
• Desktop or dashboard shells with a wallpaper.

When not to useCopy Anchor Link

• Just light, dark and system: use ThemeToggle.
• Picking one colour value: use ColorPicker.
• Language and region: use the language switcher.

ImportCopy Anchor Link

import { ThemeGallery, ReadingSettings, WallpaperPicker, readingStyleVars, wallpaperCss, parseReadingPreferences } from "@fadymondy/nasaq/web";

Quick startCopy Anchor Link

import { ReadingSettings, ThemeGallery, readingStyleVars, type ReadingPreferences } from "@fadymondy/nasaq/web";
import { useState } from "react";

const themes = [
  { id: "paper", label: "Paper", mode: "light" as const, swatches: ["var(--nq-surface)", "var(--nq-surface-soft)", "var(--nq-fg)", "var(--nq-brand)"] },
  { id: "ink", label: "Ink", mode: "dark" as const, swatches: ["var(--nq-fg)", "var(--nq-fg-muted)", "var(--nq-surface)", "var(--nq-brand)"] },
];

export function Appearance() {
  const [theme, setTheme] = useState("paper");
  const [reading, setReading] = useState<ReadingPreferences>({ fontSize: "md", width: "normal", spacing: "normal" });
  return (
    <div className="flex flex-col gap-8">
      <ThemeGallery themes={themes} value={theme} onValueChange={setTheme} />
      <ReadingSettings value={reading} onValueChange={setReading} />
      <article style={readingStyleVars(reading)}>{/* uses var(--reading-scale) etc. */}</article>
    </div>
  );
}

AnatomyCopy Anchor Link

ThemeGallery      data-slot="theme-gallery"      heading + radio group of theme-card (preview, mode icon, name, description, check)
ReadingSettings   data-slot="reading-settings"   rows of ToggleGroups, Reset, then reading-preview (live sample)
WallpaperPicker   data-slot="wallpaper-picker"   sections of wallpaper-none / wallpaper-tile radios, upload tile, dim Slider

APICopy Anchor Link

ThemeGalleryCopy Anchor Link

ReadingSettingsCopy Anchor Link

WallpaperPickerCopy Anchor Link

Helpers (pure, no React)Copy Anchor Link

ExamplesCopy Anchor Link

Wallpaper with dimming and upload:

import { WallpaperPicker, wallpaperCss } from "@fadymondy/nasaq/web";
import { useState } from "react";

export function Desk({ wallpapers }: { wallpapers: React.ComponentProps<typeof WallpaperPicker>["wallpapers"] }) {
  const [id, setId] = useState<string | null>(null);
  const [dim, setDim] = useState(20);
  const current = wallpapers.find((w) => w.id === id);
  return (
    <div style={{ background: current ? wallpaperCss(current.background) : undefined }}>
      <WallpaperPicker wallpapers={wallpapers} value={id} onValueChange={setId} dim={dim} onDimChange={setDim} onUpload={async (file) => { /* upload, then add to wallpapers */ }} />
    </div>
  );
}

AccessibilityCopy Anchor Link

• ThemeGallery and WallpaperPicker are radio groups: Tab enters, arrow keys move (following the reading direction), Space selects. The group is named by its heading.
• Wallpaper tiles have no visible text, so each has its label as its accessible name and tooltip. Use a real label, not "Wallpaper 3".
• Reading settings buttons have text or aria-labels ("Larger text"); the size steppers stop being available at the ends.
• The selected card shows a check as well as a border, so selection never relies on colour alone.

RTL & i18nCopy Anchor Link

• Text is English or Arabic through labels; pass localised theme and wallpaper names.
• The percent labels (113%) are isolated left-to-right; the grids and toggle groups follow the reading direction; the reset icon mirrors.
• The reading sample follows the page direction, so line width in ch works for Arabic too.

Styling & tokensCopy Anchor Link

Cards use border-border, bg-card, bg-nq-selected and border-primary when chosen. Theme previews take their colours from the theme's own swatches, so give token colours (var(--nq-brand)) rather than hex. Target [data-slot="theme-card"], [data-slot="wallpaper-tile"], [data-slot="reading-preview"].

Do / Don'tCopy Anchor Link

• Do apply the choice at once; the preview is only a hint.
• Do keep wallpapers readable behind text: offer the dim slider.
• Don't offer more than about eight themes; a gallery is not a catalogue.
• Don't rely on swatches alone for meaning; every theme has a name.

RelatedCopy Anchor Link

• ThemeToggle
• ColorPicker
• ToggleGroup
• Slider

LabCopy Anchor Link

https://docs.nasaqui.com/?path=/docs/components-pickers-appearance-pickers--docs