Skip to content
Compositions

ColorPalette

Stacked colour palette in the style of the Dropbox brand site: a row of overlapping, bottom-anchored square cards cropped to 16:9. Hovering or focusing a card smoothly raises it and reveals a search action that deep-links into the colours search page. The component renders only the swatch row - no card, heading, or CTA chrome. Compose those around it (a <section>, a title, a sample button wired to onSelectedIdsChange) when a surface calls for them. Cards can be flat colours, gradients, or images (see ColorPaletteItem). Image cards need a searchHex to be clickable. With selectable, clicking anywhere on a card toggles it in and out of the selection instead of linking out; selected cards keep a check visible at rest, and the selection surfaces through onSelectedIdsChange.

Cream
Copper
Terracotta
Walnut
Espresso
Cacao

Usage

import { buildSampleHref, buildSearchHref, ColorPalette, ColorPaletteItem, ColorPaletteLinkProps, ColorPaletteProps, getPaletteItemId, getSampleHex, PaletteDirection, PaletteSort, sortPaletteItems } from "@instruments/materia-ui/compositions/color-palette";

Best practices

  • Describe cards as items (kind: "color" | "gradient" | "image"), not hand-built markup - the component owns the overlap, hover-raise, and deep-link-to-search behaviour.

  • Give every image card a searchHex, otherwise it can't be searched or selected - flat colours and gradients derive theirs automatically.

  • Pass renderLink (e.g. wrapping next/link) for client-side nav - the built-in links are plain <a>; the callback must return a single anchor element.

Props

PropTypeDefaultDescription
items(required)ColorPaletteItem[]

Cards to render - flat colours, gradients, or images (see ColorPaletteItem).

sortPaletteSort

Controlled sort order

defaultSortPaletteSort

Initial sort order when uncontrolled (default "original")

onSortChange(sort: PaletteSort) => void

Fired when the sort changes; pair with sort for controlled mode.

directionPaletteDirection

Controlled stacking direction

defaultDirectionPaletteDirection

Initial stacking direction when uncontrolled (default "left-first")

onDirectionChange(direction: PaletteDirection) => void

Fired when the direction changes; pair with direction for controlled mode.

showSettingsboolean

Show the sort/direction settings popover button (default false)

selectableboolean

Let users build a selection by clicking cards - the whole card becomes a toggle instead of a search link. Selected cards keep a check visible at rest; read the selection through onSelectedIdsChange and drive any sampling CTA yourself (default false).

selectedIdsstring[]

Controlled selected ids. Ids come from item.id, falling back to kind-index for items without one - provide stable ids when selection must survive item reordering.

defaultSelectedIdsstring[]

Initial selected ids when uncontrolled

onSelectedIdsChange(selectedIds: string[]) => void

Fired when the selection changes; pair with selectedIds for controlled mode.

searchBasePathstring

Base path for the built-in search links (default "/colors")

searchLabelstring

Hover label for unnamed searchable cards (default "Search this color")

renderLink(props: ColorPaletteLinkProps) => ReactNode

Escape hatch to render links with a router-aware component (e.g. next/link). Must render a single anchor element. Defaults to a plain anchor.

classNamestring

Also exports

  • constbuildSampleHref
  • constbuildSearchHref
  • typeColorPaletteItem
  • interfaceColorPaletteLinkProps
  • interfaceColorPaletteProps
  • constgetPaletteItemId
  • constgetSampleHex
  • typePaletteDirection
  • typePaletteSort
  • constsortPaletteItems

Composition

Builds on

Button, Center, Flex, Icon, Popover, SegmentedControl