Gradient select

A little color for the text you select. Gradient select paints a customizable gradient across a native text selection, without wrapping your text in extra elements. Selection, copying, and links keep working as usual.

Try the playground.

Install

npm install @manxz/gradient-select

Or use pnpm add @manxz/gradient-select.

import gradientSelect from '@manxz/gradient-select';

const selection = gradientSelect({ colors: ['#FFB3BA', '#FFD0A8'] });

Call it in the browser after the document is available. Importing the module has no side effects and is safe during server rendering. A call on the server returns an inactive controller; initialize again in the browser, such as inside a component's mount effect.

One-line script

For a plain HTML site, add this to your page:

<script defer src="https://cdn.jsdelivr.net/npm/@manxz/[email protected]/dist/gradient-select.js" data-colors='["#FFB3BA","#FFD0A8"]'></script>

The script initializes automatically and exposes window.GradientSelection. You can also download dist/gradient-select.js from the package and host it yourself.

Colors

Choose 1–64 CSS colors. One color creates a solid highlight; two or more create a gradient. Colors are evenly spaced in the order you supply. The default is pink to peach: #FFB3BA → #FFD0A8.

selection.setColors(['#FFD1E8', '#D5C4F5', '#BBDFFA']);

Opaque, light colors work best because the selected text is black. CSS variables and context-dependent colors such as currentColor are not accepted.

API

gradientSelect(options?) starts the effect and returns a controller. Repeated calls in the same document reuse the controller.

| Member | Purpose | | --- | --- | | setColors(colors) | Update the palette immediately. | | setPreview(element) | Keep an element's text highlighted as a live sample. | | setPreview(null) | Remove the persistent sample. | | refresh() | Repaint immediately after a layout change. | | destroy() | Remove the effect, listeners, styles, and owned highlights. | | init(options?) | Start again after cleanup. | | supported | Whether the browser has the required highlighting features. | | colors | A copy of the current palette. |

The same controller methods are available through window.GradientSelection when using the script tag. Add data-manual to that tag to initialize it yourself with GradientSelection.init().

Live preview

selection.setPreview(document.querySelector('.sample'));
selection.setColors(['#BBDFFA', '#FFD1E8']);

A preview highlights the sample without changing the native selection or moving focus. A real selection takes priority. This makes it useful for color pickers and playgrounds.

Cleanup

selection.destroy();

The controller is shared within a document. Have one application-level owner initialize and clean it up.

Content Security Policy

If your site requires a nonce for inline styles, pass the permitted value:

gradientSelect({ colors: ['#FFB3BA', '#FFD0A8'], nonce: yourCspNonce });

With a script tag, put the nonce on that tag. Your policy must permit the script and the generated stylesheet. If the stylesheet is blocked, ordinary native selection remains available.

Browser behavior

Gradient select uses CSS Custom Highlights, color-mix() in OKLab, and Intl.Segmenter. Unsupported browsers and forced-color mode keep ordinary native selection. Inputs, textareas, and editable content retain their usual selection behavior.

The gradient is approximated with up to 64 highlight bands. Short selections have fewer visible steps. Multiple selection ranges, selections inside shadow roots, and selections longer than 40,000 graphemes fall back to native selection. Traversal is also capped at 10,000 text nodes.

This is an early release. Browser capabilities are checked at runtime; test the interaction in the browsers and devices your site supports.

License

MIT © Oscar Manxz