Colors

Theme-aware palette colours, your brand swatches and any exact hex, side by side.

import { useRef, useState } from "react"; import { BlockEditor, type BlockEditorHandle } from "genesis-editor"; const swatches = [ { name: "brand", hex: "#ff5a1f" }, { name: "ink", hex: "#1e3a8a" }, ]; const article = `<h3>Release notes</h3> <p><span data-text-color="red">Palette red</span> and <span data-background-color="yellow">a yellow highlight</span> follow the theme.</p> <p><span style="color:#1f6feb">Exact #1f6feb</span>, <span style="background-color:#d1fae5">#d1fae5 behind it</span>, and <span style="color:#3b0764">a dark purple</span> stay exact.</p> <p><span data-text-color="brand" style="color:#ff5a1f">Brand orange</span> comes from the integrator's swatches.</p> <p style="background-color:#fef3c7">A whole paragraph can have a colour too, here #fef3c7.</p>`; const pasted = `<p>From a web page: <span style="color: rgb(225, 62, 62)">almost palette red</span>, <span style="color: hsl(330, 100%, 45%)">hot pink</span>, <span style="background: rgba(16, 185, 129, 0.25)">a translucent green</span> and <span style="color:#222">near-black</span>.</p>`; /** Dispatches a real paste event, the same one ⌘V / Ctrl+V produces, on a new empty line. */ function pasteInto(editor: BlockEditorHandle, html: string) { const doc = editor.editor.document; const [line] = editor.editor.insertBlocks([{ type: "paragraph" }], doc[doc.length - 1], "after"); editor.editor.setTextCursorPosition(line, "start"); editor.focus(); const transfer = new DataTransfer(); transfer.setData("text/html", html); transfer.setData("text/plain", html.replace(/<[^>]+>/g, "")); editor.editor.domElement?.dispatchEvent(new ClipboardEvent("paste", { clipboardData: transfer, bubbles: true, cancelable: true })); } export default function ColorsExample() { const editor = useRef<BlockEditorHandle>(null); const [custom, setCustom] = useState(true); const [contrast, setContrast] = useState(false); const [html, setHtml] = useState(""); return ( <div className="flex flex-col gap-3"> <div className="flex flex-wrap items-center gap-x-4 gap-y-2 px-15 text-sm"> <button className="rounded-md border px-2.5 py-1 hover:bg-muted" onClick={() => editor.current && pasteInto(editor.current, pasted)}> Paste colored HTML </button> <label className="inline-flex items-center gap-1.5"> <input type="checkbox" checked={custom} onChange={(e) => setCustom(e.target.checked)} data-testid="custom-toggle" /> Custom colors </label> <label className="inline-flex items-center gap-1.5"> <input type="checkbox" checked={contrast} onChange={(e) => setContrast(e.target.checked)} data-testid="contrast-toggle" /> colorContrast="auto" </label> <button className="rounded-md border px-2.5 py-1 hover:bg-muted" onClick={() => setHtml(editor.current?.getHTML() ?? "")}> Export HTML </button> </div> <BlockEditor key={String(custom)} ref={editor} format="html" defaultValue={article} tools={{ colors: { custom, swatches }, fontSize: true, bold: true, italic: true, heading: true, link: true }} colorContrast={contrast ? "auto" : "off"} /> {html && ( <pre className="mx-15 overflow-x-auto rounded-md bg-muted p-3 text-xs whitespace-pre-wrap" data-testid="colors-html"> {html} </pre> )} </div> ); }

Palette, swatches and hex#

textColor and backgroundColor hold one of three kinds of value, never a mix:

A palette name: gray, brown, red, orange, yellow, green, blue, purple, pink. These follow the theme, so red is lighter on a dark background.
A swatch name from tools.colors.swatches, for brand colours. It renders as its hex in both themes.
Lowercase hex, #rrggbb, plus #rrggbbaa for translucent backgrounds. It looks the same in both themes.

"default" means no colour. Anything else, such as rgb(…) or uppercase hex set through the API, is drawn as the default.

{ "type": "text", "text": "Palette", "styles": { "textColor": "red" } }
{ "type": "text", "text": "Exact",   "styles": { "textColor": "#1f6feb", "backgroundColor": "#10b98140" } }
{ "type": "text", "text": "Brand",   "styles": { "textColor": "brand" } }

The color menu#

The toolbar's colour button has a Text and a Background section, each with:

Default and the nine palette colours;
your brand swatches;
Document colors: up to eight hex colours already used in the document, most used first;
Recent: the last eight custom colours, kept in localStorage;
Custom…: a hex (or any CSS colour) field, the system colour picker, and an eyedropper in browsers that have the EyeDropper API.

Hover a hex swatch to see its value.

Options#

<BlockEditor
  tools={{
    colors: {
      palette: true,   // the nine theme-aware colours (default)
      custom: true,    // document colours and Custom… (default)
      swatches: [{ name: "brand", hex: "#ff5a1f" }],
    },
  }}
  colorContrast="auto" // fix hex text that's hard to read on the current theme
/>

palette: false hides the palette and stops pasted colours snapping to it.
custom: false hides document colours and Custom…, and pasted hex that isn't close to a named colour goes to the palette colour for its hue. htmlMode="strict" does the same.
Swatch names are lowercase letters, digits and dashes, and can't be palette names. Invalid swatches are skipped.

Contrast

Hex colours don't adapt to the theme, so dark blue text can vanish in dark mode. colorContrast="auto" lightens or darkens hex text that has less than 3:1 contrast with the theme's background. Only the rendering changes; the stored colour and the exported HTML stay exact.

Pasted colours#

Any CSS colour is read: names, rgb(), hsl(), and 3-, 4-, 6- or 8-digit hex. Transparent colours, inherit and currentColor are dropped.
A colour within ΔE2000 3 of a palette colour or swatch becomes that name, so it follows the theme from then on.
Near-black text (#000, #1f1f1f, #333…), white backgrounds, and the blue sites use for links count as the default.
Everything else stays exact hex.

The import report counts pasted colours as colors.palette and colors.hex.

HTML#

Every colour is written as an inline style, so email clients and RSS readers show it. Names also get a data- attribute, so they read back as the name:

<span style="color:#e03e3e" data-text-color="red">Palette</span>
<span style="color:#1f6feb;background-color:#10b98140">Exact</span>
<span style="color:#ff5a1f" data-text-color="brand">Brand</span>

Swatch names only mean something with the same swatches. Pass them to toHTML and parseHTML on the server; the editor's getHTML() already uses its own.

import { toHTML, parseHTML } from "genesis-editor/parser";

const swatches = [{ name: "brand", hex: "#ff5a1f" }];
toHTML(blocks, { swatches });                       // brand → its hex, plus data-text-color="brand"
parseHTML(html, { tools: { colors: { swatches } } }); // data-text-color="brand" → "brand"