Skip to content

ColorPicker

C-35 · Components · Editor (Office)

All elements · ColorPicker on the Components page

Last checked 2026-10-22 · Awaiting approval · Accessibility tests

Copies the bun run a11y:approve command for ColorPicker.

ColorPicker

C-35 OfficeWCAG 2.2 AA · Passed

Popover content for font, highlight, fill and outline colors: Automatic, the theme grid (10 × 6 tints and shades), the standard row, More colors…. Each cell is labeled ("Blue, Lighter 40%"); swatches keep their true color in forced colors with a CanvasText border.

Axis / element Values
__grid · __row · __cell role=grid · row · gridcell, --_swatch is document data
data-variant="theme" gap under the first row
__label · __action · __preview section titles · Automatic / More colors… · current/new pair
aria-selected the current color
Font color
Theme colors
Standard colors

Guidance

When to use

  • Use it as popover content for font color, highlight, fill and outline in the office editors.
  • Use it with Automatic, the 10 by 6 theme grid (data-variant="theme"), the standard row and More colors….
  • Use __preview to show the current and new color side by side when a dialog edits one color.
  • Open it from the menu half of a color Split button.

When to consider something else

  • When users pick from a few named statuses or tags, use a Select or Chips; a color grid suits document formatting only. See Select.
  • When the choice is a visual style with more than color, use a Gallery. See Gallery.
  • When the color is applied at once by a default, use the primary half of a Split button and keep the picker in its menu. See SplitButton.

Usability

Do
  • Label every cell with its color name and tint, such as "Blue, Lighter 40%".
  • Mark the current color with aria-selected="true".
  • Keep More colors… available for any color not in the grid.
  • Treat --_swatch as document data; don't map it to system tokens.
  • Inside .qf-office, use Fluent Regular glyphs for Automatic and More colors… (README, Icons).
Don’t
  • Don't identify colors by swatch alone in labels, tooltips or announcements (1.4.1).
  • Don't let forced colors repaint the swatches; they keep their true color with a CanvasText border.
  • Don't remove Automatic; it resets to the theme's default text color.

Accessibility

Keyboard

ColorPicker keyboard
Keys Action
Tab / Shift+Tab Moves between Automatic, the theme grid, the standard grid and More colors….
Arrow Left / Arrow Right Moves between cells in a row.
Arrow Up / Arrow Down The binding must move to the cell above or below, as a grid requires.
Home / End Moves to the first or last cell.
Enter or Space Applies the focused color and marks it selected.
Escape Closes the popover and returns focus to the button that opened it.

Roles and names

  • Each __grid is role="grid" labeled by its __label through aria-labelledby; rows are role="row" and cells are buttons with role="gridcell".
  • Every __cell has an aria-label with the color name and an aria-selected state.
  • __action items are command Buttons with visible text.
  • Applying a color is announced through a polite live region ("Blue applied").
  • In the Colors dialog, __spectrum and __hue are role="slider" with an aria-valuetext that names the value ("Saturation 87%, brightness 71%", "210 degrees, blue"); __preview is role="img" with an aria-label naming both colors in hex.

Focus

  • Each grid is one tab stop (roving tabindex); focus starts on the selected cell when there is one.
  • Cells show a focus ring that differs from the selected outline.
  • Closing the popover returns focus to the opener.

Other requirements

  • Cells are 1rem (16px), below the 24px of 2.5.8; More colors… is the equivalent larger target, so it must always be present.
  • Swatch borders use an 18% ink mix; check light swatches such as White still show a 3:1 boundary against the popover (1.4.11).
  • In forced colors the selected cell gets a Highlight outline.
  • The custom-color field and hue strip are pointer conveniences: the RGB or HSL spin buttons and the hex field reach every color from the keyboard, and Arrow keys on the field move saturation (Left/Right) and brightness (Up/Down).

Test your implementation too. This guidance covers the element as specified here. How a screen composes it (labels, order, announcements) still needs its own keyboard and screen reader check.

Accessibility tests

WCAG 2.2 AA · Passed

Passed the gate (run 358b316 on 2026-10-22): no finding in any theme. Awaiting a person’s approval of the checklist below.

ColorPicker test checklist
Area Automated A person checks
General Passed Color is never the only cue, text alternatives say the same thing as the graphic, and the element reads the same in the light and the dark theme.
Zoom Passed At 200% zoom, at 320 CSS pixels wide and with the WCAG text-spacing overrides, nothing is lost, clipped or overlapping.
Keyboard Passed Every row of the Keyboard table works, focus is always visible and never trapped, and the tab order follows the reading order. (6 rows)
Screen reader Passed With NVDA or JAWS on Windows and VoiceOver on macOS, names, roles and states are announced as Roles and names says, and changes are announced once. (5 items)

Approving. When the checklist passes on the checked run, record it with bun run a11y:approve -- color-picker --by "Your name" and commit a11y/approvals.json with the rebuilt pages. All test status

Package

Consumers link one stylesheet, css/classic/index.css, which includes every element. The files below are where this element is defined.

ColorPicker package
Source css/classic/components/pickers.css
Specimens also use Box · Button · Card · Chip · Icon · Popover · Table · Text · Toolbar
Sprites sprites/icons.svg · sprites/office-icons.svg
React Not yet available: the React binding has not started.

Latest updates

ColorPicker latest updates
Date Version Breaking Description
2026-10-10 0.1 No ColorPicker custom colors for the Colors dialog (More colors…): .qf-color-picker__mixer holds __spectrum (a saturation and brightness field for the hue in --_hue-color, role=slider) above __hue (the hue strip, role=slider), each with a __thumb placed by --_x/--_y or --_value; __compare labels New and Current over __preview, whose two children take --_swatch. Tokens --qf-color-spectrum-height, --qf-color-hue-height, --qf-color-thumb-size and --qf-color-hue-gradient, both skins

All release notes