Overview
Read an SVG as named, recolourable parts — a part is a set of shapes, not a hex value.
SVG Parts
@absolutejs/svg-partsv0.1.0-beta.3betaFrontend & UXRead an SVG as named, recolourable parts — a part is a set of shapes, not a hex value.
#Installation
BASH
bun add @absolutejs/svg-parts#Capabilities
Overview
Read an SVG as named, recolourable parts — a part is a set of shapes, not a hex value.
Why
Recolouring a flat SVG by substituting hex values repaints every shape that shares that hex. Two unrelated shapes drawn in black can never be separated, and a design with forty shades presents forty "parts" to a customer. This library gives shapes stable ids, lets you group them into named parts, and rewrites one attribute on one element at a time — the rest of the document is returned byte for byte.
What's here
parseSvg(markup) — Drawable elements in paint order, each with a stable id, its group ancestry and the byte range of its opening tag.
paletteOf(doc) — Every distinct painted colour, in paint order.
partsFromColors(doc) — One part per colour — the migration path from a colour-keyed model.
Show 7 more
oneWholePart(doc) — Everything as a single part.
groupPart(doc, model, { name, nodeIds }) — Pull shapes into a new named part, out of whatever held them.
renamePart / ungroupPart / partOfNode — The rest of the model edits.
applyParts(doc, { model, colors }) / recolor(markup, model, colors) — Paint by part id.
withPartIds(doc, model) — The same markup with data-part / data-node, for a canvas to hit-test.
colorMapOf(model, colors) — The old colour→colour map, for code that still speaks it.
No DOM, no XML parser dependency, no browser needed.
Status
0.1.0-beta — the parser and the part model. A React selection canvas is the next slice; drawing tools are deliberately not in scope (Illustrator exists).
Outcomes
What you can build
Why
Recolouring a flat SVG by substituting hex values repaints every shape that shares that hex. Two unrelated shapes drawn in black can never be separated, and a design with forty shades presents forty "parts" to a customer. This library gives shapes stable ids, lets you group them into named parts, and rewrites one attribute on one element at a time — the rest of the document is returned byte for byte.
What's here
parseSvg(markup) — Drawable elements in paint order, each with a stable id, its group ancestry and the byte range of its opening tag.
Hardening checklist
Production guidance
Make every external boundary explicitPin the deployed @absolutejs/svg-parts version, replace example or memory-backed dependencies with durable implementations, bound external calls, protect credentials, and emit enough evidence to retry or recover safely.
Follow in order
Troubleshooting path
1
Trace from the first failed boundary
Reproduce the smallest canonical @absolutejs/svg-parts example, confirm the supported entry point and version in the API explorer, then inspect the first boundary that did not produce its documented result.
#@absolutejs/svg-parts quick start
Partial snippet# @absolutejs/svg-parts
TS
import {
parseSvg,
partsFromColors,
groupPart,
recolor
} from '@absolutejs/svg-parts';
const doc = parseSvg(markup);
// A flat design arrives as one part per colour — the same model a
// colour-keyed recolour gives you, so nothing has to be re-entered.
let model = partsFromColors(doc);
// Then split it the way the artwork actually reads.
model = groupPart(doc, model, { name: 'crest', nodeIds: ['n3', 'n4'] });
// Colour by part id. Shapes another part owns are untouched, even if they
// were drawn in the same colour.
const painted = recolor(markup, model, { crest: '#c8102e' });#Public entry points
Supported entry points declared by this project’s package manifest. Internal dist paths are not part of the package contract.
Public package entry point declared in package.json.
@absolutejs/svg-parts@absolutejs/svg-parts/react
#Package commands
Scripts declared by this project’s package manifest.
bun run buildrm -rf dist && bun build ./src/index.ts ./src/react.tsx --root ./src --outdir dist --target bun --external react --external react/* && tsc --emitDeclarationOnly --project tsconfig.json
bun run check:packagebun run format && bun run typecheck && bun run test && bun run build && absolute-changelog check
bun run formatprettier --write "./**/*.{js,ts,json,md}"
bun run testbun test
bun run typechecktsc --noEmit
#API reference
Search the declarations exported by the current package type files. Expand a symbol to inspect its source-backed signature.
31 symbols
TS
type ApplyInput = {
/** partId → colour. Anything missing keeps the colour it was drawn in. */
colors: Record<string, string>;
model: PartModel;
};@absolutejs/svg-parts