Color Area

A two-dimensional gradient for adjusting two channels of a color at once.

Usage

import { ColorArea } from '@appica/ui-react/color-area'
import { parseColor } from '@appica/ui-react/color'

<ColorArea defaultValue="hsb(217, 76%, 96%)" xChannel="saturation" yChannel="brightness" />

ColorArea paints a plane of a color space and puts a draggable thumb on it. The horizontal axis drives xChannel, the vertical axis drives yChannel (increasing upwards), and the third channel of the space is held constant - it's what the plane is a slice of. Pair it with a slider for that third channel and you have a color picker.

The value is a Color: a plain object you get from parseColor, or any CSS color string passed straight to value / defaultValue. Because it's a plain object and not a class instance, it serializes cleanly across the server/client boundary. Every handler is called with a Color, which you format with formatColor.

const [color, setColor] = useState(() => parseColor('#3b82f6'))

<ColorArea value={color} onValueChange={setColor} xChannel="saturation" yChannel="brightness" />

The color space comes from the value, so parseColor('hsl(…)') gives an HSL area and a hex string gives an RGB one. Set colorSpace to override it and convert on the way in.

A space and a format are different things, and it's worth being clear about which is which. The space is the set of axes you move along (rgb, hsl, hsb); the format is how the result gets written down. Hex is a format, not a space - #3b82f6 and rgb(59, 130, 246) are the same color in the same space, spelled differently. Pick in whichever space suits the control, then call formatColor for whatever you need to store.

Give the area a name with aria-label: it has no visible text, and the name is what a screen reader reads before the channel values.

Inside a Color Picker the value and the handlers can be left off entirely: the area reads and writes the picker's color through context.

Examples

Color spaces

Three spaces can be plotted: rgb, hsl, and hsb. Each is separable, so the browser paints the plane from two stacked CSS gradients over a solid base - no per-pixel work, and it renders during SSR. Below is the same blue, sliced along a different pair of channels in each.

RGB

HSL

HSB

import { ColorArea } from '@appica/ui-react/color-area'

const PLANES = [
  { space: 'rgb', xChannel: 'red', yChannel: 'green', label: 'RGB' },
  { space: 'hsl', xChannel: 'saturation', yChannel: 'lightness', label: 'HSL' },
  { space: 'hsb', xChannel: 'saturation', yChannel: 'brightness', label: 'HSB' },
] as const

export default function ColorAreaSpaces() {
  return (
    <div className="grid grid-cols-3 gap-6">
      {PLANES.map(({ space, xChannel, yChannel, label }) => (
        <div key={space} className="flex flex-col items-center gap-2">
          <ColorArea
            defaultValue="#3b82f6"
            colorSpace={space}
            xChannel={xChannel}
            yChannel={yChannel}
            aria-label={`${label} color area`}
            className="size-32"
          />
          <span className="text-foreground-muted text-xs font-medium">{label}</span>
        </div>
      ))}
    </div>
  )
}

Building a picker

ColorArea covers two channels, so the third needs its own control: a Color Slider. Add a second one for alpha and a Color Swatch for the result, and you have the shape most pickers take. Every part reads and writes the same Color, so composing them is just sharing one piece of state.

#3b82f5

'use client'

import { useState } from 'react'
import { ColorArea } from '@appica/ui-react/color-area'
import { ColorSlider } from '@appica/ui-react/color-slider'
import { ColorSwatch } from '@appica/ui-react/color-swatch'
import { type Color, formatColor, parseColor } from '@appica/ui-react/color'

export default function ColorAreaPicker() {
  const [color, setColor] = useState<Color>(() => parseColor('hsb(217, 76%, 96%)'))

  return (
    <div className="flex w-full max-w-56 flex-col gap-3">
      <ColorArea
        value={color}
        onValueChange={setColor}
        xChannel="saturation"
        yChannel="brightness"
        aria-label="Saturation and brightness"
      />
      <ColorSlider channel="hue" value={color} onValueChange={setColor} />
      <ColorSlider channel="alpha" value={color} onValueChange={setColor} />
      <div className="flex items-center gap-3">
        <ColorSwatch color={color} />
        <span className="font-mono text-xs text-nowrap">
          {color.alpha < 1 ? formatColor(color, 'rgba') : formatColor(color, 'hex')}
        </span>
      </div>
    </div>
  )
}

Output formats

The area works in one space and hands you a Color; formatColor writes that out in any format you like, with no second control needed. Here the same pick is shown four ways at once - drag the thumb and every line updates.

hex: #3b82f6
rgb: rgb(59, 130, 246)
hsl: hsl(217.22, 91.22%, 59.8%)
hsb: hsb(217.22, 76.02%, 96.47%)

'use client'

import { useState } from 'react'
import { ColorArea } from '@appica/ui-react/color-area'
import { type Color, formatColor, parseColor } from '@appica/ui-react/color'

const FORMATS = ['hex', 'rgb', 'hsl', 'hsb'] as const

export default function ColorAreaFormats() {
  const [color, setColor] = useState<Color>(() => parseColor('#3b82f6'))

  return (
    <div className="flex w-64 flex-col gap-4">
      <ColorArea
        value={color}
        onValueChange={setColor}
        colorSpace="hsb"
        xChannel="saturation"
        yChannel="brightness"
        aria-label="Theme color"
        className="size-64"
      />
      <dl className="grid gap-1 text-xs">
        {FORMATS.map((format) => (
          <div key={format} className="flex gap-2">
            <dt className="text-foreground-muted w-8">{format}</dt>
            <dd className="text-foreground-intense font-mono">{formatColor(color, format)}</dd>
          </div>
        ))}
      </dl>
    </div>
  )
}

Choosing channels

Any two channels of the space can go on the axes. Here red runs horizontally and blue vertically, leaving green as the constant - move the thumb and only two of the three readouts change.

red: 59
green: 130
blue: 246

'use client'

import { useState } from 'react'
import { ColorArea } from '@appica/ui-react/color-area'
import { type Color, formatChannelValue, parseColor } from '@appica/ui-react/color'

export default function ColorAreaChannels() {
  const [color, setColor] = useState<Color>(() => parseColor('rgb(59, 130, 246)'))

  return (
    <div className="flex flex-col gap-3">
      <ColorArea
        value={color}
        onValueChange={setColor}
        xChannel="red"
        yChannel="blue"
        aria-label="Red and blue"
        className="size-56"
      />
      <dl className="text-foreground-muted grid grid-cols-3 gap-2 text-xs tabular-nums">
        {(['red', 'green', 'blue'] as const).map((channel) => (
          <div key={channel} className="flex flex-col">
            <dt className="capitalize">{channel}</dt>
            <dd className="text-foreground-intense font-medium">{formatChannelValue(color, channel)}</dd>
          </div>
        ))}
      </dl>
    </div>
  )
}

Sizing

The area is size-56 (224px) by default and takes any size through className. The corner radius carries to the gradient and the ring, so a fully rounded area works too. thumbProps reaches the thumb, for a smaller one on a small area.

import { ColorArea } from '@appica/ui-react/color-area'

export default function ColorAreaSizing() {
  return (
    <div className="flex w-full max-w-90 flex-col gap-4">
      <ColorArea
        defaultValue="hsb(280, 70%, 90%)"
        xChannel="saturation"
        yChannel="brightness"
        aria-label="Wide color area"
        className="h-32 w-full rounded-2xl"
      />
      <div className="flex items-end gap-4">
        <ColorArea
          defaultValue="hsb(140, 70%, 90%)"
          xChannel="saturation"
          yChannel="brightness"
          aria-label="Small color area"
          className="size-16 rounded-full"
          thumbProps={{ className: 'size-4' }}
        />
        <ColorArea
          defaultValue="hsb(30, 70%, 90%)"
          xChannel="saturation"
          yChannel="brightness"
          aria-label="Medium color area"
          className="size-24 rounded-xs"
        />
      </div>
    </div>
  )
}

Forms

xName and yName name the two hidden range inputs the component already renders for accessibility, so the axis values submit with a plain HTML form. No hidden field or onSubmit plumbing needed.

'use client'

import { useState } from 'react'
import { ColorArea } from '@appica/ui-react/color-area'
import { Button } from '@appica/ui-react/button'

export default function ColorAreaForm() {
  const [submitted, setSubmitted] = useState<string | null>(null)

  return (
    <form
      className="flex flex-col items-start gap-4"
      onSubmit={(event) => {
        event.preventDefault()
        const data = new FormData(event.currentTarget)
        setSubmitted(`saturation ${data.get('saturation')}, brightness ${data.get('brightness')}`)
      }}
    >
      <ColorArea
        defaultValue="hsb(217, 76%, 96%)"
        xChannel="saturation"
        yChannel="brightness"
        xName="saturation"
        yName="brightness"
        aria-label="Brand color"
        className="size-40"
      />
      <Button type="submit" size="sm">
        Submit
      </Button>
      {submitted ? <p className="text-foreground-muted font-mono text-xs">{submitted}</p> : null}
    </form>
  )
}

Disabled

disabled blocks interaction and swaps the gradient for a flat muted fill inside a dashed outline, dimmed.

import { ColorArea } from '@appica/ui-react/color-area'

export default function ColorAreaDisabled() {
  return (
    <ColorArea
      defaultValue="hsb(217, 76%, 96%)"
      xChannel="saturation"
      yChannel="brightness"
      aria-label="Brand color"
      disabled
      className="size-40"
    />
  )
}

RTL

Every Appica UI component supports right-to-left layouts out of the box. Set the dir attribute on a container (commonly your <html> element) so CSS logical properties resolve correctly, and wrap your tree in DirectionProvider so direction-aware behavior (roving focus, popup placement, and the like) follows the same direction.

import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}

The horizontal axis mirrors: the x channel's minimum sits on the right edge, the gradient flows the same way, and ←/→ swap so the arrow that moves the thumb toward the maximum is still the one pointing at it. The vertical axis is unaffected. For setup details and caveats, see the RTL guide.

لون العلامة التجارية

API reference

ColorArea

Prop	Type	Default	Description
`value`	`Color \| string`	-	Selected color. Pass a `Color` or any CSS color string to control the component. Inside a `ColorPicker` it can be left off: the control then reads and writes the picker's color.
`defaultValue`	`Color \| string`	`'#ffffff'`	Color selected before any interaction, when the component is uncontrolled.
`onValueChange`	`(value: Color) => void`	-	Fires on every change, including each frame of a drag.
`onValueCommitted`	`(value: Color) => void`	-	Fires once a drag ends or a key press settles, with the color that was landed on.
`colorSpace`	`'rgb' \| 'hsl' \| 'hsb'`	value's space	Color space the axes operate in. Defaults to the space of the value, so a color parsed from `hsl(...)` gives an HSL area and a hex one gives an RGB area. The space is independent of the format you store: convert on the way out.
`xChannel`	`ColorChannel`	first free	Channel mapped to the horizontal axis. Defaults to the first channel of the color space that `yChannel` has not taken.
`yChannel`	`ColorChannel`	first free	Channel mapped to the vertical axis, increasing upwards. Defaults to the first channel of the color space left free by `xChannel`.
`disabled`	`boolean`	`false`	Prevent interaction and dim the area.
`xName`	`string`	-	Name of the hidden horizontal input, used when submitting an HTML form.
`yName`	`string`	-	Name of the hidden vertical input, used when submitting an HTML form.
`form`	`string`	-	`id` of the `<form>` the hidden inputs belong to, when they sit outside it.
`thumbProps`	`ComponentPropsWithoutRef<'span'>`	-	Props for the thumb element, for styling or a test id.
`aria-label`	`string`	`'Color picker'`	Accessible name, read before the channel values.
`className`	`string`	-	Extra classes on the root, merged via `tailwind-merge`.

Every other <div> attribute is forwarded to the root. The root carries data-space, data-disabled and data-dragging; the parts are addressable through data-slot (color-area, color-area-surface, color-area-thumb).

Color utilities

The color model ships from its own subpath, @appica/ui-react/color, and is shared by every color component.

import { parseColor, formatColor, convertColor } from '@appica/ui-react/color'

Export	Signature	Description
`Color`	`RgbColor \| HslColor \| HsbColor \| OklchColor`	A color value. A plain object with a `space` tag, its three channels, and `alpha`.
`ColorSpace`	`'rgb' \| 'hsl' \| 'hsb' \| 'oklch'`	A supported color space.
`ColorChannel`	`'red' \| 'green' \| 'blue' \| 'hue' \| … \| 'alpha'`	A single adjustable component of a color.
`parseColor`	`(value: string) => Color`	Parses hex (3, 4, 6 or 8 digits), `rgb()`, `hsl()`, `oklch()` and `hsb()`, comma or space separated. Throws on bad input.
`safeParseColor`	`(value: string) => Color \| undefined`	Same, returning `undefined` instead of throwing.
`formatColor`	`(color, format?) => string`	Serializes to a CSS string. Defaults to `'css'`, the shortest form for the color's own space.
`convertColor`	`(color, space) => Color`	Converts into another space, through sRGB.
`getChannelValue` / `withChannelValue`	`(color, channel[, value]) => number \| Color`	Reads a channel, or returns a copy with it clamped and set.
`getChannelRange`	`(space, channel) => ColorChannelRange`	Bounds and increments of a channel: `minValue`, `maxValue`, `step`, `pageSize`.
`getColorChannels`	`(space) => [ColorChannel, ColorChannel, ColorChannel]`	The three channels of a space, in canonical order.
`getColorSpaceAxes`	`(space, axes?) => ColorAxes`	Resolves `xChannel`, `yChannel` and the leftover `zChannel`.
`getChannelName` / `formatChannelValue`	`(channel) => string`	Display name of a channel, and a channel's value with its unit.

Accessibility

The root is a role="group" holding two visually hidden <input type="range">, one per axis, so assistive technology gets a real value, bounds, and step for each channel. Only the focused axis is in the tab order.
aria-valuetext on both inputs spells out all three channels of the space, so the constant channel is announced too. aria-roledescription marks the control as a two-dimensional slider.
Keyboard: ←/→ move the x channel and ↑/↓ the y channel by one step, Shift with an arrow moves by the page step, Page Up·Down move the y channel by the page step, and Home/End move the x channel by the page step.
The thumb is a white rim with a faint dark ring on each side of it, so it keeps an edge over any point of the plane in either theme - including when the picked color is itself white. forced-color-adjust: none keeps the gradient intact in forced-colors mode.
The thumb's position is never transitioned, so it sits exactly under the pointer. The only animation is the scale while it is pressed, and that honors prefers-reduced-motion.

Actions & Inputs

Data Display

Decoration & Effects

Layout

Menus

Navigation

Overlays

Status & Feedback