Custom Color Picker

Replace the built-in color picker with your own component

Every surface that renders a color picker accepts an optional ColorSelector prop, letting you replace the built-in picker with your own component. Use this to match your design system, integrate a third-party picker library, or restrict the palette users can choose from.

Overview

The built-in ColorSelector (theme colors, standard colors, user-defined colors, hex input and eye dropper) is the default everywhere. Passing your own component to the ColorSelector prop swaps it at that surface:

Component	Where the picker appears
TextColorSelector	Toolbar text color dropdown
BackgroundColorSelector	Toolbar fill color dropdown
BorderSelector	Border color inside the border menu
BorderColorSelector	Standalone border color dropdown
SheetTabs	"Change color" in the tab context menu
FloatingCellEditor	Text and fill color pickers

Because it is a plain prop, you can swap the picker on one surface and keep the default on the others.

Writing a custom picker

Your component receives ColorSelectorProps:

import type { ColorSelectorProps } from "@rowsncolumns/spreadsheet";

const BrandColorSelector = ({
  color,
  onChange,
  theme,
  resetButtonTitle = "Automatic",
  userDefinedColors,
  onAddUserDefinedColor,
}: ColorSelectorProps) => {
  const brandColors = ["#1E40AF", "#F59E0B", "#10B981", "#EF4444"];
  return (
    <div className="flex flex-col gap-1 p-2">
      <button onClick={() => onChange?.(undefined)}>{resetButtonTitle}</button>
      <div className="flex gap-1">
        {brandColors.map((value) => (
          <button
            key={value}
            aria-label={`Select ${value}`}
            style={{ backgroundColor: value, width: 24, height: 24 }}
            onClick={() => onChange?.(value)}
          />
        ))}
      </div>
    </div>
  );
};

ColorSelectorProps:

Prop	Type	Description
color	Color | null	Currently selected color
onChange	(color: Color | undefined) => void	Call with the new color; undefined resets to automatic
theme	SpreadsheetTheme	Active theme, for rendering theme color swatches
resetButtonTitle	string	Label for the reset action ("Automatic", "No fill", "Reset")
userDefinedColors	string[]	Custom palette colors (see User-Defined Colors)
onAddUserDefinedColor	(color: string) => void	Add a color to the custom palette

Usage in the toolbar

import {
  Toolbar,
  TextColorSelector,
  BackgroundColorSelector,
  BorderSelector,
} from "@rowsncolumns/spreadsheet";

<Toolbar>
  <TextColorSelector
    color={currentCellFormat?.textFormat?.color}
    theme={theme}
    onChange={handleTextColorChange}
    ColorSelector={BrandColorSelector}
  />
  <BackgroundColorSelector
    color={currentCellFormat?.backgroundColor}
    theme={theme}
    onChange={handleBackgroundColorChange}
    ColorSelector={BrandColorSelector}
  />
  <BorderSelector
    borders={currentCellFormat?.borders}
    theme={theme}
    onChange={onChangeBorder}
    ColorSelector={BrandColorSelector}
  />
</Toolbar>

BorderSelector forwards the component to the border color picker inside the borders menu.

Sheet tab color picker

SheetTabs forwards the component to the "Change color" submenu of the tab context menu:

import { SheetTabs } from "@rowsncolumns/spreadsheet";

<SheetTabs
  sheets={sheets}
  activeSheetId={activeSheetId}
  theme={theme}
  onChangeSheetTabColor={onChangeSheetTabColor}
  ColorSelector={BrandColorSelector}
/>

If you already supply a custom ContextMenu to SheetTabs, render your own picker inside it directly — the ColorSelector prop is forwarded to your context menu via SheetTabContextMenuProps.

Floating cell editor

import { FloatingCellEditor } from "@rowsncolumns/spreadsheet";

<FloatingCellEditor
  sheetId={activeSheetId}
  activeCell={activeCell}
  onChange={onChange}
  onChangeFormatting={onChangeFormatting}
  ColorSelector={BrandColorSelector}
/>

Best practices

1. Call onChange with undefined for your reset action so "Automatic"/"No fill" behaves like the built-in picker

2. Respect resetButtonTitle — each surface passes the right label for its context

3. Reuse one component across surfaces for a consistent experience, or override only the surfaces you need

4. Keep userDefinedColors support if your app also uses the custom palette, so both features compose