---
title: "Headless color presets | Nutrient Web SDK"
canonical_url: "https://www.nutrient.io/guides/web/headless/color-presets/"
md_url: "https://www.nutrient.io/guides/web/headless/color-presets.md"
last_updated: "2026-05-15T19:10:05.084Z"
description: "Read annotation color presets from any Nutrient Web SDK namespace and render your own pickers that respect the customer’s annotationToolbarColorPresets configuration."
---

# Headless color presets

Every annotation namespace that has color exposes a `getColorPresets()` method. The returned list mirrors the swatches the default toolbar would render, including any overrides from the customer’s [`annotationToolbarColorPresets`](https://www.nutrient.io/api/web/NutrientViewer.Configuration.html#annotationToolbarColorPresets) configuration callback. Build one color picker component, point it at any namespace, and your picker stays in sync with however the customer customizes the SDK.

Looking for the visual side of this? See the `tools.contextual` [slot](https://www.nutrient.io/guides/web/user-interface/ui-customization/supported-slots.md#tools) for replacing the inline color picker that appears in the annotation property toolbar. This page covers the programmatic surface you’ll call from inside that custom UI.

## When to use this

Reach for the headless color preset API when you’re building:

- A custom color picker that mirrors the default SDK swatches.

- A per-tool color palette that switches its source as the active tool changes.

- A design system color picker that needs to respect the customer’s preset configuration without reimplementing the resolution logic.

- A test or storybook entry that needs to enumerate the swatches the SDK currently uses.

## API reference

Call `getColorPresets()` on the namespace whose presets you want to read.

| Namespace                                            | Returns presets for                                              |
| ---------------------------------------------------- | ---------------------------------------------------------------- |
| `instance.annotations.textMarkup.getColorPresets()`  | Highlight, underline, strikeout, and squiggly colors.            |
| `instance.annotations.shape.getColorPresets()`       | Rectangle, ellipse, line, polyline, and polygon stroke and fill. |
| `instance.annotations.link.getColorPresets()`        | Link annotation border color.                                    |
| `instance.annotations.redaction.getColorPresets()`   | Redaction fill, outline, and overlay text colors.                |
| `instance.annotations.measurement.getColorPresets()` | Measurement annotation stroke color.                             |
| `instance.annotations.text.getColorPresets()`        | Text annotation font, background, and border colors.             |

The shape of the returned object varies by namespace. Most follow the same pattern: an object keyed by the property being colored, with each entry holding a `presets` array of `ColorPreset` values, plus a `showColorPicker` Boolean.

Per-namespace shapes:

- **text-markup** — Grouped by `highlight` and `markup`.

- **text** — Grouped by `fontColor`, `backgroundColor`, and `borderColor`.

- **redaction** — Grouped by `fillColor`, `outlineColor`, and `overlayTextColor`.

- **shape**, **link**, and **measurement** — Same per-property pattern, with one or two color groups each.

A `ColorPreset` has two fields: a required `color` (a `NutrientViewer.Color`) and an optional `localization` string. The default UI uses `localization` for tooltips and `aria-label`s. Surface it in your own pickers if you want the swatches to be accessible and localized.

## Example: A highlight color picker

Render the swatches the default markup toolbar would show for the highlight tool, and apply the chosen color to the current annotation preset:

```js

const instance = await NutrientViewer.load({
  container: "#viewer",

  document: "contract.pdf"
});

const presets = instance.annotations.textMarkup.getColorPresets();

const palette = document.getElementById("highlight-palette");
presets.highlight.presets.forEach((preset) => {
  const swatch = document.createElement("button");
  swatch.className = "color-swatch";
  swatch.style.backgroundColor = preset.color.toHex();
  // `localization` is a translation key, pipe it through your i18n layer
  // if you have one, or fall back to a sensible default.
  if (preset.localization) {
    swatch.title = preset.localization;
    swatch.setAttribute("aria-label", preset.localization);
  }
  swatch.onclick = () => {
    // Update the preset value, then activate it. `setCurrentAnnotationPreset`
    // only switches which preset is active, it does not accept a value patch.
    instance.setAnnotationPresets((presets) => ({...presets,
      highlight: {...presets.highlight, color: preset.color }
    }));
    instance.setCurrentAnnotationPreset("highlight");
  };
  palette.appendChild(swatch);
});

```

## How preset resolution works

The values returned by `getColorPresets()` are the **resolved** ones; they reflect both the SDK defaults and any overrides from the customer’s [`annotationToolbarColorPresets`](https://www.nutrient.io/api/web/NutrientViewer.Configuration.html#annotationToolbarColorPresets) callback. You don’t need to rerun the resolution logic in your own code: A custom picker built on `getColorPresets()` picks up customer overrides automatically.

## Related

- `annotationToolbarColorPresets` [configuration](https://www.nutrient.io/api/web/NutrientViewer.Configuration.html#annotationToolbarColorPresets) — How customers customize the preset list.

- [Headless ink](https://www.nutrient.io/guides/web/headless/ink.md), [text markup](https://www.nutrient.io/guides/web/headless/text-markup.md), and [text annotations](https://www.nutrient.io/guides/web/headless/text-annotations.md) — The per-namespace pages that use this pattern.
---

## Related pages

- [Headless callout annotations](/guides/web/headless/callout.md)
- [Headless image annotations](/guides/web/headless/image.md)
- [Annotation clipboard](/guides/web/headless/clipboard.md)
- [Headless](/guides/web/headless.md)
- [Headless ink annotations](/guides/web/headless/ink.md)
- [Headless stamp annotations](/guides/web/headless/stamp.md)
- [Headless link annotations](/guides/web/headless/link.md)
- [Headless note annotations](/guides/web/headless/note.md)
- [Redactions from text selection](/guides/web/headless/redactions-from-selection.md)
- [Programmatic notes panel](/guides/web/headless/notes-panel.md)
- [Headless text annotations](/guides/web/headless/text-annotations.md)
- [Headless shape annotations](/guides/web/headless/shape.md)
- [Headless text markup](/guides/web/headless/text-markup.md)