# Appearance

> The Appearance section of an AI product’s settings. Theme, density and text sizes stay a draft until people save.

Canonical: https://hextaui.com/blocks/appearance
Last updated: 2026-10-29

## Overview

Appearance groups everything about how the app looks into one section. Theme cards show a small window in each theme, drawn in the accent you've picked, so the choice is clear before you save.

System follows the device and says which one it is right now. High contrast strengthens edges and text and keeps backgrounds neutral, so the tint slider turns off while it's picked.

The accent hue is a real color track with eight quick picks under it, and the readout names the color, like Blue 250°. Background tint mixes that accent into the surfaces. Density and chat font cards show a sample of each option, and the two text sizes are steppers with limits.

Reduce motion and Reduce transparency say when the device already asks for either.

Everything is a draft until it's saved. The save bar from Settings rises as soon as something differs, Discard brings back the saved look, and Reset puts every option back to its default as a draft you can still discard.

## Installation

### Step 1: Get HextaUI Pro

One payment unlocks every block, including future ones. [See pricing](https://hextaui.com/pricing).

### Step 2: Add the Pro registry to components.json

```json title="components.json"
{
  "registries": {
    "@hextaui-pro": {
      "url": "https://hextaui.com/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${HEXTAUI_PRO_TOKEN}"
      }
    }
  }
}
```

### Step 3: Add your token

Create a token on your [account page](https://hextaui.com/account) and put it in `.env.local` as `HEXTAUI_PRO_TOKEN`.

### Step 4: Add the block

```bash
npx shadcn@latest add @hextaui-pro/appearance
```

## Usage

### Save to your API

Pass the saved values and an async onSave. Nothing is sent until someone presses Save in the bar. Throw to show your message in the bar and keep their picks.

```tsx
"use client"

import { IconPalette } from "@tabler/icons-react"

import { SettingsSection, SettingsShell } from "../settings/settings"
import { AppearanceSettings, type AppearanceValues } from "@/components/blocks/appearance/appearance"

export function AppearancePage({ appearance }: { appearance: AppearanceValues }) {
  return (
    <SettingsShell
      sections={[{ id: "appearance", label: "Appearance", icon: <IconPalette /> }]}
      className="h-svh"
    >
      <SettingsSection id="appearance">
        <AppearanceSettings
          values={appearance}
          onSave={async (values) => {
            const response = await fetch("/api/appearance", {
              method: "PUT",
              body: JSON.stringify(values),
            })
            if (!response.ok) throw new Error("Check your connection and try again.")
          }}
        />
      </SettingsSection>
    </SettingsShell>
  )
}
```

### Apply the saved look

Once saved, apply the values to your app however it themes itself. normalizeAppearance repairs anything stored by an older version, so a bad value never breaks the page.

```tsx
"use client"

import * as React from "react"

import { AppearanceSettings, normalizeAppearance, type AppearanceValues } from "@/components/blocks/appearance/appearance"

function applyAppearance(values: AppearanceValues) {
  const root = document.documentElement
  const systemDark = window.matchMedia("(prefers-color-scheme: dark)").matches
  const dark = values.theme === "dark" || values.theme === "contrast" || (values.theme === "system" && systemDark)
  root.classList.toggle("dark", dark)
  root.dataset.contrast = values.theme === "contrast" ? "more" : "normal"
  root.dataset.density = values.density
  root.dataset.chatFont = values.chatFont
  root.dataset.motion = values.reduceMotion ? "reduce" : "full"
  root.dataset.transparency = values.reduceTransparency ? "reduce" : "full"
  root.style.setProperty("--accent-hue", String(values.hue))
  root.style.setProperty("--accent-tint", `${values.intensity}%`)
  root.style.setProperty("--text-interface", `${values.interfaceSize}px`)
  root.style.setProperty("--text-code", `${values.codeSize}px`)
}

export function AppearanceForm({ stored }: { stored: Partial<AppearanceValues> | null }) {
  const [saved, setSaved] = React.useState(() => normalizeAppearance(stored))

  React.useEffect(() => applyAppearance(saved), [saved])

  return (
    <AppearanceSettings
      values={saved}
      onSave={async (values) => {
        const response = await fetch("/api/appearance", {
          method: "PUT",
          body: JSON.stringify(values),
        })
        if (!response.ok) throw new Error("Check your connection and try again.")
        setSaved(values)
      }}
    />
  )
}
```

## Anatomy

The parts you compose, from the outside in.

| Part | Description |
| --- | --- |
| `AppearanceSettings` | The section's content: the groups of options, wired to the shell's save bar. |
| `normalizeAppearance` | Turns stored or partial values into valid ones: clamps sizes, wraps the hue and falls back for unknown names. |
| `appearanceDefaults` | The values Reset goes back to when you don't pass your own. |

## API reference

### AppearanceSettings

Use inside a SettingsSection. Also accepts every div prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `values` | `AppearanceValues` | – | What's saved now: { theme, hue, intensity, density, chatFont, interfaceSize, codeSize, reduceMotion, reduceTransparency }. Invalid values are repaired, and the repair doesn't count as an unsaved change. |
| `onSave` | `(values) => void \| errors \| Promise<void \| errors>` | – | Save the draft. Throw to show the message in the save bar and keep the draft. |
| `defaults` | `AppearanceValues` | `appearanceDefaults` | What Reset puts back. |

### AppearanceValues

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `"system" \| "light" \| "dark" \| "contrast"` | `"system"` | System follows prefers-color-scheme. |
| `hue` | `number` | `250` | The accent's OKLCH hue, 0 to 359. |
| `intensity` | `number` | `30` | How much of the accent tints backgrounds, 0 to 100. |
| `density` | `"compact" \| "comfortable"` | `"comfortable"` | Space between and inside messages. |
| `chatFont` | `"sans" \| "serif" \| "mono"` | `"sans"` | The font for messages. |
| `interfaceSize` | `number` | `14` | Text size in pixels, 12 to 18. |
| `codeSize` | `number` | `13` | Code size in pixels, 11 to 20. |
| `reduceMotion` | `boolean` | `false` | Stop spinners and sliding panels. |
| `reduceTransparency` | `boolean` | `false` | Solid backgrounds instead of blurred ones. |

## Keyboard

| Key | Action |
| --- | --- |
| `←` `→` | In the theme, density or font cards, pick the previous or next card. On the hue track, move one degree. |
| `Shift` `→` | On the hue track, move 15 degrees. Page Up and Page Down do the same. |
| `Home` `End` | On the hue track, jump to either end. |
| `↑` `↓` | In a text size field, change the size by one pixel. |
| `⌘` `S` | Save while something is unsaved. Ctrl+S on Windows and Linux. |

## Accessibility

- Each card group is a radio group named by its row, and each card is named by its own label, so screen readers hear "Dark, radio, 3 of 4".
- The hue track reads its color by name, like "Blue, 250 degrees", and the quick picks are toggle buttons named by color.
- Reset keeps focus after it runs and announces that the defaults are back and need saving.

## Built with

The free HextaUI components Appearance is made from. Each one installs on its own.

- [Button](https://hextaui.com/docs/button) - Buttons in every variant and size, with a built-in loading, success and error flow that skips the spinner for fast requests.
- [Slider](https://hextaui.com/docs/slider) - Pick a value or a range by dragging, tapping the track or using the keys, with jumps that glide and an optional value bubble.
- [Switch](https://hextaui.com/docs/switch) - An on/off toggle you can tap, press or drag, with a thumb that stretches under your finger and an optional pending state for saves.

## Code

2 files, added to components/blocks/appearance.
