react-visual-chips

Flexible SVG chip components for React (icons, patterns, gradients, brands). Published as react-visual-chips on npm.

Contents: Package structure · Install · Imports & migration · Chip namespace · BaseChip props · Complete API reference · SVG helper reference · Chip catalog · Contributing

Package structure

Published output lives under dist/ (see package.json "files"). Source layout:

| Path | Role | |------|------| | src/index.ts | Main library entry: re-exports chips (except Test), BaseChip, createChip, Chip, system/svg, system/design, color helpers, interaction hooks. | | src/chip.ts | Chip namespace object — grouped references to every chip component (for discovery / listChips). Not a React component. | | src/registry.ts | Public entry for listChips() / listChipsByCategory() — re-exports chipRegistry.ts without pulling the registry into the main bundle when unused. | | src/chipRegistry.ts | Registry implementation (flat / grouped chip lists for galleries and tooling). | | src/components/Chip/ | BaseChip (root <svg> + app tile + contexts), createChip factory, types (BaseChipProps, ChipFilter), layout/style context, preserveAspectRatio helpers. | | src/chips/<Category>/ | One folder per category (Banking, Infrastructure, Generic, Pattern, Gradient, Flag, Images, Test). Each chip is a .tsx file; index.ts re-exports the category. | | src/system/svg/ | Low-level SVG primitives (Rect, Path, Positioned, Noise, Pathfinder, Rotate, Scale, Symbol, Use, path builder, gradients, etc.). | | src/system/color/ | resolveChipColor, grayscale / monochrome helpers, CSS filter builder for the root <svg>. | | src/system/design/ | useChipDesign — spacing/radius tokens + semantic palette wired to chip color context. | | src/system/interaction/ | Optional interaction hooks (useHoverEffect, useFocusEffect). | | vite.config.ts | Library build: multiple entry points for tree-shaking by domain (banking, generic, ...). | | demo/ | Vite + React dev app; imports from ../src via alias. | | .github/workflows/ci.yml | CI: npm ci, npm test, npm run build. |

flowchart TB
  subgraph entry [Entry]
    indexTs[src/index.ts]
  end
  subgraph chips [Chips]
    categories[chips/Banking Infrastructure Generic Pattern Gradient Flag Images Test]
  end
  subgraph core [Core]
    BaseChip[BaseChip + createChip + contexts]
  end
  subgraph system [System]
    svg[svg primitives + path builder]
    color[color pipeline]
    design[design tokens]
  end
  indexTs --> categories
  indexTs --> BaseChip
  categories --> BaseChip
  BaseChip --> svg
  BaseChip --> color
  categories --> design

Install & build

npm install react-visual-chips

Peer dependencies: React 18+ and react-dom 18+.

git clone ... && cd react-chips
npm install
npm run build
npm test

Imports & bundle size

Prefer named imports per icon or subpath imports so bundlers only pull what you use:

import { Server, Home } from "react-visual-chips";
import { Server } from "react-visual-chips/infrastructure";
import { Home } from "react-visual-chips/generic";

Subpaths (see package.json "exports"): react-visual-chips, react-visual-chips/banking, react-visual-chips/infrastructure, react-visual-chips/generic, react-visual-chips/pattern, react-visual-chips/gradient, react-visual-chips/flag, react-visual-chips/images, react-visual-chips/test, react-visual-chips/registry.

Tree-shaking note: import { Chip } eagerly pulls every chip into your bundle. Use named or subpath imports for production.

Migrating before 0.0.31

• listChips / listChipsByCategory / ChipEntry — import from react-visual-chips/registry instead of the package root.
• Test / demo chips (SvgDemoShapes, Layers, Dusk, utilities, …) — import from react-visual-chips/test only; they are no longer re-exported from the root entry.
• parseViewBox — no longer exported from the root package; it remains an internal helper on ChipLayoutContext. Prefer useChipLayout() inside BaseChip artwork.

The Chip namespace (not <Chip />)

There is no <Chip /> JSX component. Chip is a plain object grouping components for namespaced access and the registry:

import { Chip } from "react-visual-chips";

<Chip.Infrastructure.Server width={64} aria-label="Server" />
<Chip.Generic.Home width={64} />

Equivalent named imports (usually better for tree-shaking):

import { Server } from "react-visual-chips";

<Server width={64} aria-label="Server" />

listChips() / listChipsByCategory() return { category, name, Component } for each registered chip -- useful for icon pickers and docs. Import them from react-visual-chips/registry so the main bundle stays lean:

import { listChipsByCategory, type ChipEntry } from "react-visual-chips/registry";

API: BaseChipProps (every icon)

Every chip is a ForwardRefExoticComponent<BaseChipProps> produced by the createChip factory. Icons implement artwork inside BaseChip; you normally only pass props to the icon component.

All standard SVGProps<SVGSVGElement> (event handlers, className, id, aria-*, role, style, etc.) are spread onto the root <svg> -- no manual allowlist needed.

Layout & canvas

| Prop | Type | Default | Description | |------|------|---------|-------------| | width | number \| string | 64 (CSS px) | SVG width. | | height | number \| string | (same as width if omitted) | SVG height. | | viewBox | string | "0 0 100 100" | SVG viewBox. | | viewportPosition | "start" \| "center" \| "end" | "center" | Maps to preserveAspectRatio (horizontal alignment). | | hasAppContainer | boolean | false | Rounded "app tile" behind artwork; artwork is clipped to that shape (overflow hidden). | | appContainerFill | string | (light gray) | Tile background color (hex/rgb). Ignored when appContainerGradient is set. | | appContainerStroke | string | (light border) | Tile outline color. | | appContainerStrokeWidth | number | 1 | Tile outline width. | | appContainerRadius | number \| "auto" | "auto" | Corner radius in viewBox units ("auto" uses the default min(18, 0.18 × min side)). | | appContainerGradient | { stops: { offset, color }[], angleDeg? } | -- | Linear gradient tile fill; stop colors run through the same color mode as other chip paints. | | appContainerSheen | boolean \| { opacity?, angleDeg? } | -- | Optional diagonal white sheen over the tile (off by default). true uses subtle defaults. | | clipContent | boolean | false | Without an app tile, clips artwork to the rectangular viewBox. (With hasAppContainer, clipping is always on.) |

Color

| Prop | Type | Default | Description | |------|------|---------|-------------| | colorMode | "color" \| "monochrome" \| "bw" | "color" | How fills/strokes are resolved. | | monochromeBase | string | -- | Hex/rgb tint for monochrome (non-accent paths); near-black falls back to plain grayscale. | | baseColor | string | -- | Accent override (hex, rgb). Note: only #hex and rgb()/rgba() are reliably parsed. hsl(), oklch(), and named colors pass through without mode conversion. |

Inside artwork, useChipDesign() exposes fill, base(), line(), palette(), paletteLine(), etc., all wired through resolveChipColor. Use palette("amber", 500) (and PALETTE) for explicit Tailwind-like hues; keep semantic keys for roles (surface, accent, warning, …).

Stroke

| Prop | Type | Default | Description | |------|------|---------|-------------| | strokeWidth | number | -- | Default stroke width for inner artwork (via context). | | strokeFill | string | -- | Root stroke color intent (mapped through color pipeline). |

A default strokeLinejoin="round" is set on the artwork group to prevent miter spikes on tight corners.

CSS filters

Filters are grouped into a single filter object instead of flat props:

<Server
  filter={{
    brightness: 0.8,
    contrast: 1.2,
    cssFilter: "drop-shadow(0 2px 4px rgba(0,0,0,.3))",
  }}
/>

| filter.* | Type | Default | Description | |------------|------|---------|-------------| | brightness | number | 1 | CSS brightness() | | contrast | number | 1 | CSS contrast() | | saturate | number | 1 | CSS saturate() | | hueRotate | number | 0 | CSS hue-rotate() (degrees) | | grayscale | number | 0 | CSS grayscale() | | sepia | number | 0 | CSS sepia() | | invert | number | 0 | CSS invert() | | cssFilter | string | -- | Extra CSS filter string appended after structured filters. | | custom | string | -- | Deprecated alias of cssFilter; prefer cssFilter. |

Noise overlay

| Prop | Type | Default | Description | |------|------|---------|-------------| | noise | boolean \| NoiseOptions | -- | true = default grain; object = Noise options. |

NoiseOptions (omit children): intensity (0--1), pattern (0--1, coarse to fine), displacement (0--1, warp), opacity, blendMode, baseFrequency, numOctaves, seed, stitchTiles, x, y, width, height.

When hasAppContainer is true, the noise overlay is automatically clipped to the rounded container shape.

Accessibility & events

All standard SVG event handlers and ARIA attributes are accepted directly since BaseChipProps extends SVGProps<SVGSVGElement>:

<Server
  aria-label="Production server"
  onClick={() => console.log("clicked")}
  onMouseEnter={() => setHovered(true)}
  tabIndex={0}
/>

When aria-label is set, role defaults to "img"; otherwise it defaults to "presentation" with aria-hidden="true".

Types (TypeScript)

Import from the package root:

import type {
  AppContainerGradientConfig,
  AppContainerSheenConfig,
  BaseChipProps,
  ChipColorMode,
  ChipFilter,
  ViewportPosition,
  BwHint,
  ResolveColorOptions,
} from "react-visual-chips";

Creating chips with createChip

The createChip factory wraps an artwork component in BaseChip, adding forwardRef and displayName automatically:

import { createChip } from "react-visual-chips";
import { useChipDesign } from "react-visual-chips";
import { Group, Path, Positioned } from "react-visual-chips";

function MyIconArt() {
  const d = useChipDesign();
  return (
    <Positioned anchor="center-center" anchorPosition={[50, 50]}>
      <Group>
        <Path fill={d.base()} d="M 20 80 L 50 20 L 80 80 Z" />
      </Group>
    </Positioned>
  );
}

export const MyIcon = createChip("MyIcon", MyIconArt);

// Optional third argument: default `BaseChipProps` merged before caller props (overridable).
export const France = createChip("France", FranceArt, { hasAppContainer: true });

All chips in this library use createChip. Gradient, Pattern, Flag, and Test (SvgDemoEffects) chips that fill the tile default to hasAppContainer: true with full-bleed 0..100 artwork (no inset "safe" margin).

SVG path builder

Two-layer utility for constructing SVG d attribute strings.

Shape helpers (zero SVG knowledge needed)

import { polyline, polygon, roundedRect } from "react-visual-chips";

// Open path through points
<Path d={polyline([30, 50], [44, 64], [70, 38])} />

// Closed polygon
<Path d={polygon([14, 34], [86, 34], [86, 76], [14, 76])} />

// Rectangle with corner radius (as a path, useful for Pathfinder)
<Path d={roundedRect(10, 10, 80, 60, 5)} />

Fluent builder (curves, arcs, compound paths)

import { svgPath } from "react-visual-chips";

const d = svgPath()
  .M(14, 52).L(50, 16).L(86, 52)
  .V(84).C(86, 86, 84, 88, 82, 88)
  .H(18).C(16, 88, 14, 86, 14, 84)
  .Z()
  .toString();

<Path d={d} />

Supports all SVG path commands: M, m, L, l, H, h, V, v, C, c, S, s, Q, q, A, a, Z.

FxGroup: shadow, grain texture, pointer feedback

Compose CSS drop-shadow, optional Noise grain, and hover / press visuals (scale + shadow lift) on a single <g> — without adding effect props to every shape primitive.

• shadow: true (medium preset), "sm" / "md" / "lg", or any CSS filter fragment (e.g. drop-shadow(...), blur(...)). Combined with style.filter and interaction filters via mergeSvgFilters.
• texture: true for default grain, or Noise options (intensity, pattern, …). Renders Noise with children (grain painted on top).
• interactive: wires usePointerSurfaceStyle — pointer cursor, scale on hover/press, extra drop-shadow while active. Not device vibration.

Helpers: buildDropShadow, SHADOW_SM / SHADOW_MD / SHADOW_LG, mergeSvgFilters.

Clipping: Strong shadows can be cut off when the parent BaseChip uses a rounded app tile with clipping. Prefer a roomier viewBox, weaker lg shadow, or a chip without the tile for demos.

import { BaseChip, FxGroup, Rect } from "react-visual-chips";

<BaseChip width={96} height={96} hasAppContainer={false} aria-label="Fx demo">
  <FxGroup shadow="md" texture={{ intensity: 0.15 }} interactive>
    <Rect x={25} y={25} width={50} height={50} radiusToken="md" fill="#38bdf8" />
  </FxGroup>
</BaseChip>

Use usePointerSurfaceStyle alone when you only need handlers + filter/scale and will merge styles yourself. useHoverEffect remains the minimal single-state hover helper.

SVG transform primitives

In addition to Positioned, Relative, and Absolute (translate), the library provides:

import { Rotate, Scale } from "react-visual-chips";

<Rotate angle={45} cx={50} cy={50}>
  <Rect x={25} y={25} width={50} height={50} />
</Rotate>

<Scale factor={0.5}>
  <Circle cx={50} cy={50} r={40} />
</Scale>

<Scale factor={[2, 0.5]}> {/* non-uniform */}
  <Rect x={0} y={0} width={50} height={50} />
</Scale>

SVG symbol reuse

For repeated shapes, use Symbol + Use to reduce DOM nodes:

import { Defs, Symbol, Use, Rect } from "react-visual-chips";

<Defs>
  <Symbol id="rack-row" viewBox="0 0 76 24">
    <Rect width={76} height={24} radiusToken="md" fill={d.fill("surface")} />
  </Symbol>
</Defs>
<Use href="#rack-row" x={12} y={20} />
<Use href="#rack-row" x={12} y={52} />

Color modes

• color: Original fills/strokes from design tokens.
• bw: Binary light/dark via luminance; use resolveFill / resolveStroke with { bw: 'light' | 'dark' } on specific shapes when needed.
• monochrome: BT.601 grayscale; with a parseable monochromeBase (not near-black), non-accent colors tint toward that base. baseColor is grayscaled, restored toward the accent, then blended with monochromeBase in linear-light space.

Color mixing uses linear-light interpolation (gamma-correct) for perceptually accurate midpoints.

Shape primitives (tokens and shorthands)

Import space, radius, and stroke from react-visual-chips / react-visual-chips/system/design (re-exported from the package root).

• space — use at call sites: x={space[4]}, y={space["2"]} (not hidden props on every element).
• radiusToken on Rect — maps to rx/ry; ignored if rx/ry are set.
• strokeToken on Rect, Circle, Line, Ellipse — maps to strokeWidth from the stroke scale; ignored if strokeWidth is set. For strokes tied to chip props, use useChipDesign sw / line() instead.
• Ellipse — center={[cx, cy]}, size={40} (circle) or size={[dx, dy]} (diameters for rx/ry).
• Line — start / end tuples, or angleDeg + length with start (or x1/y1) for polar segments; 0° = +x, 90° = +y (SVG down).
• Polyline — same points tuple API as Polygon, open path (<polyline>).

Layout primitives

• Positioned + anchor (top-left ... bottom-right) + anchorPosition={[x, y]} -- align local artwork to the chip canvas (Positioned.tsx).
• Rect / Group optional layoutAnchor / layoutAnchorPosition -- same idea for single primitives.
• Rotate / Scale -- transform wrappers (see SVG transform primitives).
• useSvgId(prefix) -- generates unique, SVG-safe id strings (no colons from React's useId).

Chip catalog

All components accept BaseChipProps and support ref forwarding. Import by name from react-visual-chips or from the matching subpath (e.g. react-visual-chips/infrastructure).

| Category | Component | Chip.* access | |----------|-----------|-----------------| | Banking | Mastercard | Chip.Banking.Mastercard | | Infrastructure | Server, Database, Cloud, Network, Container, Pipeline, LoadBalancer, Globe, Lock | Chip.Infrastructure.<Name> | | Generic | Home, Settings, User, Search, Mail, Folder, Check, Star | Chip.Generic.<Name> | | Pattern | Stripes, Dots, Grid | Chip.Pattern.<Name> | | Gradient | Sunset, Ocean, Aurora | Chip.Gradient.<Name> | | Flag | France, Austria, Netherlands | Chip.Flag.<Name> | | Images | Twilight, Coastal, Meadow, Dunes — abstract landscapes (react-visual-chips/images) | Chip.Images.<Name> | | Test | SvgDemoShapes, SvgDemoLayout, SvgDemoEffects, Layers, … (SVG helper demos) — import from react-visual-chips/test | Chip.Test.<Name> |

Example:

import { Mastercard } from "react-visual-chips";
import { Grid } from "react-visual-chips/pattern";

<Mastercard width={48} colorMode="monochrome" monochromeBase="#4f46e5" aria-label="Card" />
<Grid width={48} noise={{ intensity: 0.4 }} aria-label="Grid" />

Demo (local dev)

The demo resolves the library from ../src via a Vite alias.

cd demo && npm install && npm run dev

From repo root (after installing root + demo deps):

npm run demo:only

API reference

This section lists every public export from the published package (see package.json "exports" and src/index.ts). All chip components are React.forwardRef wrappers around BaseChip and accept BaseChipProps unless noted.

Package entry points

| Subpath | Module file | What it exposes | |---------|-------------|-----------------| | react-visual-chips | dist/index.js | Main barrel: chips (except Test), BaseChip, createChip, Chip, SVG system, design tokens, color helpers, interaction hooks, and all related types (see tables below). | | react-visual-chips/banking | dist/banking.js | Mastercard only. | | react-visual-chips/infrastructure | dist/infrastructure.js | Infrastructure icons (see Prebuilt chips). | | react-visual-chips/generic | dist/generic.js | Generic icons. | | react-visual-chips/pattern | dist/pattern.js | Pattern fills. | | react-visual-chips/gradient | dist/gradient.js | Gradient chips. | | react-visual-chips/flag | dist/flag.js | Flag chips. | | react-visual-chips/images | dist/images.js | Abstract landscape chips. | | react-visual-chips/test | dist/test.js | Demo / utility showcase chips (including all Util* chips). Not re-exported from the main barrel. | | react-visual-chips/registry | dist/registry.js | listChips, listChipsByCategory, ChipEntry type. |

Core chip primitives (main barrel)

| Export | Kind | Description | |--------|------|-------------| | BaseChip | component | Root <svg>: optional rounded app tile, clip, noise overlay, color pipeline, filter string from filter prop + style.filter merge. Provides ChipStyleContext and ChipLayoutContext. | | createChip | function | createChip(name, Art, defaults?) — wraps artwork in BaseChip, sets displayName. Art is () => ReactElement \| null. | | Chip | const object | Namespace Chip.<Category>.<Name> — see Chip namespace. Pulls all categories into one import (poor tree-shaking). | | ChipStyleContext | React context | Value shape (via useChipStyle()): colorMode, monochromeBase, baseColor, resolveFill(color, opts?), resolveStroke(color, opts?), strokeWidth, strokeColor. Throws if used outside BaseChip. | | useChipStyle | hook | Reads ChipStyleContext; must run under BaseChip. | | ChipLayoutContext | React context | Parsed viewBox as minX, minY, contentWidth, contentHeight. | | useChipLayout | hook | Reads layout context; must run under BaseChip. |

Not exported from the main package: parseViewBox (internal; used by BaseChip and tests). Importing from source paths is unsupported for consumers.

Types (from react-visual-chips)

These are exported as types from the main entry (see src/index.ts and export type blocks).

| Type | Purpose | |------|---------| | BaseChipProps | All props for any chip: dimensions, viewBox, hasAppContainer, tile gradient/sheen, noise, colorMode, monochromeBase, baseColor, viewportPosition, strokeWidth, strokeFill, filter, clipContent, plus Omit<SVGProps<SVGSVGElement>, "width" \| "height" \| "viewBox" \| "children" \| "filter" \| "strokeWidth">. | | ChipColorMode | "color" \| "monochrome" \| "bw" | | ViewportPosition | "start" \| "center" \| "end" — maps to SVG preserveAspectRatio. | | BwHint | "auto" \| "light" \| "dark" — used in ResolveColorOptions for bw mode. | | ResolveColorOptions | { bw?: BwHint; accentBase?: boolean } | | AppContainerGradientStop | { offset: string; color: string } | | AppContainerGradientConfig | { stops: AppContainerGradientStop[]; angleDeg?: number } | | AppContainerSheenConfig | { opacity?: number; angleDeg?: number } | | ChipFilter | Structured CSS filters on artwork: brightness, contrast, saturate, hueRotate, grayscale, sepia, invert, cssFilter, deprecated custom. |

SVG-related types (props + helpers): AnchorName, RelativeProps, AbsoluteProps, FlexProps, FlexItemProps, FlexDirection, FlexAlign, FlexJustify, BlockProps, TextProps, PositionedProps, RectProps, CircleProps, EllipseProps, LineProps, PolygonProps, PolylineProps, TriangleProps, SvgStarProps (alias for StarProps), PathProps, ChatBubbleProps, GroupProps, SettingsWheelProps, FxGroupProps, DropShadowOptions, ShadowPreset, DefsProps, FilterProps, GaussianBlurProps, ClipPathProps, MaskProps, PathfinderProps, PathfinderOperation, PathfinderMaskBounds, LinearGradientProps, RadialGradientProps, StopProps, PatternProps, NoiseProps, NoiseOptions, RotateProps, ScaleProps, SkewProps, SymbolProps, UseProps, FullBleedRectProps, LinearGradientFillProps, LinearGradientStop, RadialGradientFillProps, RadialGradientStop, PatternFillProps, BandsProps, BandsDirection, ArcSegmentProps, MirrorProps, FeDropShadowProps, FeColorMatrixProps, FeCompositeProps, FeBlendProps, FeMergeProps, FeMergeNodeProps, FeOffsetProps, FeFloodProps, FeImageProps.

Design types (from export * of system/design): SpaceToken, RadiusToken, StrokeToken, SemanticColorKey, PaletteFamily, PaletteShade, ChipDesign.

Other types: ChipCssFilterInput, PointerSurfaceHandlers, UsePointerSurfaceStyleOptions, ChipEntry (registry subpath only).

Registry API (react-visual-chips/registry)

import { listChips, listChipsByCategory, type ChipEntry } from "react-visual-chips/registry";

| Export | Description | |--------|-------------| | listChips() | Returns ChipEntry[]: { category, name, Component } for every component on Chip. | | listChipsByCategory() | Same data grouped by category, preserving key order from Chip. | | ChipEntry | { category: string; name: string; Component: ComponentType<BaseChipProps> } |

Test subpath (react-visual-chips/test)

Exports everything from src/chips/Test/index.ts: SvgDemoShapes, SvgDemoLayout, SvgDemoEffects, Layers, Desertscape, Dusk, testUtilityChips (object of all Util* components), TestUtilityChipKey, and each showcase component UtilAbsolute, UtilArcSegment, UtilBands, UtilBlock, UtilChatBubble, UtilClipPath, UtilDefs, UtilFeBlend, UtilFeColorMatrix, UtilFeComposite, UtilFeDropShadow, UtilFeFlood, UtilFeImage, UtilFeMerge, UtilFeOffset, UtilFilter, UtilFlex, UtilFullBleedRect, UtilFxGroup, UtilGaussianBlur, UtilGroup, UtilLinearGradient, UtilLinearGradientFill, UtilMask, UtilMirror, UtilNoise, UtilPathfinder, UtilPattern, UtilPatternFill, UtilPositioned, UtilRadialGradient, UtilRadialGradientFill, UtilRelative, UtilRotate, UtilScale, UtilSettingsWheel, UtilSkew, UtilSvgPath, UtilSvgRoot, UtilSymbolUse, UtilText, UtilUseSvgId.

Prebuilt chip components (by category)

Every name is a named export from the main package and from its category subpath.

| Category | Components | |----------|------------| | Banking | Mastercard | | Infrastructure | Server, Database, Cloud, Network, Container, Pipeline, LoadBalancer, Globe, Lock | | Generic | Home, Settings, User, Search, Mail, Folder, Check, Star | | Pattern | Stripes, Dots, Grid | | Gradient | Sunset, Ocean, Aurora | | Flag | France, Austria, Netherlands | | Images | Twilight, Coastal, Meadow, Dunes |

Design tokens (export * from main barrel)

From src/system/design:

| Export | Description | |--------|-------------| | space | Object of numeric spacing keys ("0", "1", … "25", px, …) → viewBox units. Type SpaceToken. | | radius | none, xs, sm, md, lg, xl, 2xl, 3xl, full. Type RadiusToken. | | stroke | hairline, sm, md, lg, xl. Type StrokeToken. | | layout | Named layout presets (rack, tile, panel, globe, pipeline, …). | | semantic | Record SemanticColorKey → { hex, opts? } for role colors (surface, surfaceMuted, surfaceStrong, ink, inkMuted, border, borderMuted, accent, accentMuted, positive, warning, negative, highlight). | | PALETTE | Tailwind-style palette map; channels 400–700 per hue family. | | getPaletteHex(family, shade?) | Returns hex string; PaletteShade is 400 \| 500 \| 600 \| 700. | | useChipDesign() | Returns ChipDesign: space, radius, strokeWidth (token map), layout, sw (resolved stroke width), fill(key), strokeSemantic(key), line(key?), base(), baseLine(), resolveFill, resolveStroke, palette(family, shade?), paletteLine(family, shade?). Must run inside BaseChip (same rule as useChipStyle). |

Color utilities (main barrel)

| Export | Description | |--------|-------------| | resolveChipColor(mode, color, monochromeBase?, options?) | Central color resolver for color / monochrome / bw modes. | | normalizeChipColorString(input) | Normalizes keywords to palette / hex where supported. | | chipColorKeywordKey(color) | Maps a keyword to a palette family key when applicable. | | convertToMonochrome(color, baseColor) | Monochrome tint helper. | | buildChipCssFilter(input: ChipCssFilterInput) | Builds a CSS filter string; ChipCssFilterInput matches structured fields + cssFilter. | | applyColorMode | Deprecated — wraps resolveChipColor with a fixed signature. |

Note: helpers such as parseToRgb, relativeLuminance, convertToGrayscale, mixRgbColors, and luminanceToBinary live under src/system/color/ but are not re-exported from react-visual-chips today; only import them from published APIs above or vendor the logic if you need them.

Interaction hooks (main barrel)

| Export | Description | |--------|-------------| | usePointerSurfaceStyle(options?) | Pointer hover/press scale + drop-shadow; returns { style, interactionStyle, interactionFilter, handlers } (see UsePointerSurfaceStyleOptions, PointerSurfaceHandlers). | | useHoverEffect(hoverStyle) | Boolean hover state; returns { style?, onMouseEnter, onMouseLeave }. | | useFocusEffect(focusStyle) | Boolean focus state; returns { style?, onFocus, onBlur }. |

SVG helper components reference

Source: src/system/svg/. All listed symbols are exported from react-visual-chips unless noted. Thin wrappers forward all standard SVG attributes on the underlying element via SVGProps<…> (see TypeScript types); use MDN for attributes not listed here.

Shorthand opportunities (not implemented today)

These are possible API extensions for consistency or ergonomics; the current API is in the subsections below.

| Area | Idea | |------|------| | Rect | Tuple shorthands for position/size, e.g. xy={[x,y]}, wh={[w,h]} (today: x, y, width, height, or size). | | Circle / Ellipse | diameter as alias for size on circle; rx/ry shortcuts on ellipse. | | Line | from / to as aliases of start / end. | | Polygon / Polyline | Already support tuple arrays for points; points={[x,y][]} is the shorthand. | | Rotate | angleDeg alias for angle (matches other components that use degrees in prop names). | | Scale | scale alias for factor. | | Text | font shorthand combining fontSize + fontFamily (today: size + fontFamily). | | Pattern | tile as alias for width/height together. | | Thin DOM wrappers (Defs, Filter, Stop, LinearGradient, RadialGradient, Path, fe*) | Intentionally minimal; domain-specific shorthands belong in higher-level components (LinearGradientFill, Noise, etc.). |

Root SVG and context

| Export | Props / behavior | |--------|------------------| | SvgRoot | SVGProps<SVGSVGElement>; defaults xmlns = http://www.w3.org/2000/svg, role = "presentation". | | SvgOriginContext | React context value { ox, oy } — current origin in viewBox space. Default {0,0}. | | useSvgOrigin() | Returns SvgOrigin. |

Anchor helpers (no BaseChip required)

| Export | Signature / behavior | |--------|----------------------| | AnchorName | Type: "top-left" | "top-center" | "top-right" | "center-left" | "center-center" | "center-right" | "bottom-left" | "bottom-center" | "bottom-right". | | containerAnchorPoint(layout, anchor) | Returns [x,y] on the chip canvas for that anchor. layout is ChipLayoutContextValue (minX, minY, contentWidth, contentHeight). | | computeAnchorTranslate(layout, anchor, anchorPosition) | Returns { tx, ty } so a child’s local point anchorPosition aligns to anchor. |

Pure geometry helpers

| Export | Role | |--------|------| | mergeRectDimensions | Merges optional size (number or [w,h]) into width / height on rect props. | | mergeLineEndpoints | Resolves start, end, optional angleDeg + length with x1…y2. | | mergeCircleGeometry | center, size → cx, cy, r. | | mergeEllipseGeometry | center, size (number or [dx,dy]) → cx, cy, rx, ry. | | mergePolygonPoints / mergePolylinePoints | points as string or [x,y][] → SVG points attribute. |

Layout groups

| Component | Props (beyond SVGProps<SVGGElement> where applicable) | |-----------|------------------------------------------------------------| | Positioned | anchor: AnchorName; anchorPosition: [x,y] local point (default [0,0]); optional width, height (metadata). Requires ChipLayoutContext (inside BaseChip). Wraps children in <g transform="translate(…)"> + updates SvgOriginContext. | | Relative | x, y (default 0) — local translate; updates SvgOriginContext. transform omitted from props type (set by component). | | Absolute | x, y (default 0) — position in viewBox space; compensates for parent SvgOriginContext. | | Group | Optional layoutAnchor, layoutAnchorPosition, layoutWidth, layoutHeight — when layoutAnchor is set, wraps <g> in Positioned. | | Flex | direction: "row" | "column" (default "row"); gap, align, justify, mainLength, x, y; children must use Flex.Item (see FlexItem). Remaining props on <g>. | | FlexItem | w, h (required); children. | | Block | Same as Flex with direction="column" fixed. Block.Item = Flex.Item. | | Text | size → maps to fontSize when fontSize omitted; fontFamily default sans-serif. Otherwise standard SVGProps<SVGTextElement> (with fontSize / fontFamily in the type). |

Shapes and paths

| Component | Props / notes | |-----------|---------------| | Rect | All SVGProps<SVGRectElement> except width/height are merged; width, height, size (number or [w,h]), radiusToken (RadiusToken → rx/ry if unset), strokeToken (StrokeToken → strokeWidth if unset), layoutAnchor + layoutAnchorPosition (wraps in Positioned). | | Circle | center [cx,cy]; size (diameter → r); strokeToken. Standard circle attributes override helpers. | | Ellipse | center; size as number (circle) or [dx,dy] (ellipse diameters); strokeToken. | | Line | start, end as [x,y]; or angleDeg + length with start or x1/y1; end wins over polar form; strokeToken. | | Polygon | points: string or [x,y][]. | | Polyline | Same as Polygon for points. | | Triangle | size (number or [w,h]); center; builds polygon points (see buildTrianglePoints in source). Other props on <polygon>. | | SvgStar (Star in system/svg) | jerks (number of tips, default 5); bloat inner/outer ratio (default 0.5); size, center, rotationDeg (default -90); buildStarPoints in source. | | Path | SVGProps<SVGPathElement> — thin wrapper; use svgPath() / polyline / polygon / roundedRect for d. |

Predefined artwork

| Export | Description | |--------|-------------| | ChatBubble | d optional (default CHAT_BUBBLE_DEFAULT_D). Other SVGProps<SVGPathElement>. | | CHAT_BUBBLE_DEFAULT_D | Default bubble path string. | | SettingsWheel | size (default 44), cx / cy (default 50), strokeLinecap, strokeLinejoin, strokeWidth (scaled for inner 24×24 art); rest forwarded to both <path> elements. SETTINGS_WHEEL_PATH_OUTER, SETTINGS_WHEEL_PATH_HUB path constants. |

Gradients, patterns, defs

| Component | Props / behavior | |-----------|-------------------| | Defs | SVGProps<SVGDefsElement>. | | Filter | SVGProps<SVGFilterElement>. | | GaussianBlur | SVGProps<SVGFEGaussianBlurElement> (<feGaussianBlur>). | | ClipPath | SVGProps<SVGClipPathElement>. | | Mask | SVGProps<SVGMaskElement>. | | LinearGradient | SVGProps<SVGLinearGradientElement>. | | RadialGradient | SVGProps<SVGRadialGradientElement>. | | Stop | SVGProps<SVGStopElement>. | | Pattern | SVGProps<SVGPatternElement>; default patternUnits = userSpaceOnUse. | | LinearGradientFill | idPrefix (default "lg-fill"); stops: { offset, color, stopOpacity? }[]; optional angleDeg (object bounding box + rotation); gradientProps extra on LinearGradient; rectProps on FullBleedRect. Renders Defs + FullBleedRect. | | RadialGradientFill | idPrefix (default "rg-fill"); stops; gradientProps (defaults cx/cy/r to centered); rectProps. | | PatternFill | idPrefix; tileWidth, tileHeight; patternTransform; patternProps; children (tile content); rectProps. | | FullBleedRect | x, y, width, height optional overrides; else from useChipLayout() (requires BaseChip). Other SVGProps<SVGRectElement> except fixed geometry keys. |

Transforms, symbol, use

| Component | Props | |-----------|--------| | Rotate | angle (degrees); cx, cy origin (default 0); children in <g transform={rotate(angle,cx,cy)}>. | | Scale | factor: number or [sx,sy]. | | Skew | skewX, skewY (degrees); optional cx, cy for skew origin. | | Symbol | SVGProps<SVGSymbolElement>. | | Use | SVGProps<SVGUseElement> (e.g. href / xlinkHref). | | Mirror | horizontal, vertical booleans — flip around viewBox center (requires ChipLayoutContext). |

Effects, noise, and composition

| Component | Props / behavior | |-----------|-------------------| | Noise | intensity (0–1, default 0.35); pattern (0–1 fineness); displacement (0–1 warp); deprecated opacity; blendMode; baseFrequency, numOctaves, seed, stitchTiles; x, y, width, height (default from layout or 0 0 100 100). With children, grain masked to alpha. | | FxGroup | shadow: boolean | "sm" | "md" | "lg" | raw CSS filter string; texture: boolean | NoiseOptions; interactive: wires usePointerSurfaceStyle. Merges style.filter with shadow + pointer. Standard SVGProps<SVGGElement> + pointer handlers. | | Pathfinder | operation: "union" | "subtract" | "intersect" | "exclude"; children: tuple [base, modifier]; optional maskBounds when outside BaseChip. | | Bands | colors: string[]; direction: "horizontal" | "vertical" — equal stripes over viewBox (requires BaseChip). |

Arc and path helpers

| Export | Description | |--------|-------------| | ArcSegment | cx, cy, outerRadius, innerRadius (default 0), startAngleDeg, endAngleDeg, plus PathProps except d. | | buildArcSegmentPath(...) | Pure function returning d string for the same geometry. |

Shadow utilities

| Export | Description | |--------|-------------| | buildDropShadow | DropShadowOptions: dx, dy, blur, color → drop-shadow(...) CSS fragment. | | SHADOW_SM, SHADOW_MD, SHADOW_LG | Preset strings. | | ShadowPreset | "sm" | "md" | "lg". | | resolveShadowPreset | Maps boolean | preset | string → CSS filter string or undefined. | | mergeSvgFilters | Concatenates multiple filter strings (space-separated). |

IDs and path builders

| Export | Description | |--------|-------------| | useSvgId(prefix?) | Hook; default prefix "svg"; returns stable id safe for url(#id) (strips : from React useId). | | polyline | (...points: [number, number][]) → open path d. | | polygon | Closed path d. | | roundedRect | (x, y, w, h, r?) → rounded rect d. | | svgPath | Returns fluent builder with M, L, H, V, C, Q, A, Z, etc., and fromRoundedRect. Note: SvgPathBuilder has S / s but no T / t (smooth quadratic). |

SVG filter primitives (fe*)

Each component is a thin wrapper: props type = SVGProps<SVGFE…Element> for the matching element.

| Component | DOM element | |-----------|-------------| | FeDropShadow | <feDropShadow> | | FeColorMatrix | <feColorMatrix> | | FeComposite | <feComposite> | | FeBlend | <feBlend> | | FeMerge | <feMerge> | | FeMergeNode | <feMergeNode> | | FeOffset | <feOffset> | | FeFlood | <feFlood> | | FeImage | <feImage> |

SVG toolkit (main barrel) — quick index

| Category | Symbols | |----------|---------| | Root / context | SvgRoot, SvgOriginContext, useSvgOrigin | | Anchor math | containerAnchorPoint, computeAnchorTranslate, AnchorName (type) | | Merge helpers | mergeRectDimensions, mergeLineEndpoints, mergeCircleGeometry, mergeEllipseGeometry, mergePolygonPoints, mergePolylinePoints | | Layout | Positioned, Relative, Absolute, Group, Flex, FlexItem, Block, Text | | Shapes | Rect, Circle, Ellipse, Line, Polygon, Polyline, Triangle, SvgStar, Path | | Predefined | ChatBubble, CHAT_BUBBLE_DEFAULT_D, SettingsWheel, SETTINGS_WHEEL_PATH_OUTER, SETTINGS_WHEEL_PATH_HUB | | Gradients / patterns | Defs, Filter, GaussianBlur, ClipPath, Mask, LinearGradient, RadialGradient, Stop, Pattern, LinearGradientFill, RadialGradientFill, PatternFill, FullBleedRect | | Transforms | Rotate, Scale, Skew, Symbol, Use, Mirror | | Effects | Noise, FxGroup, Pathfinder, Bands, buildDropShadow, mergeSvgFilters, resolveShadowPreset, SHADOW_SM, SHADOW_MD, SHADOW_LG | | Arc | ArcSegment, buildArcSegmentPath | | Utils | useSvgId, polyline, polygon, roundedRect, svgPath | | fe* | FeDropShadow, FeColorMatrix, FeComposite, FeBlend, FeMerge, FeMergeNode, FeOffset, FeFlood, FeImage |

Contributing

Icons & categories

1. Pick or create a category under src/chips/<Category>/ (PascalCase folder matching existing style).
2. Add a chip file (e.g. MyIcon.tsx) that:
   • Imports createChip from components/Chip/createChip.
   • Uses useChipDesign() for colors/stroke width where appropriate.
   • Uses system/svg primitives (Positioned, Path, Rect, path builder, ...) for artwork in a 0 0 100 100 (or custom) coordinate system.
   • Exports via export const MyIcon = createChip("MyIcon", MyIconArt);
3. Export the component from that category's index.ts.
4. Register it in src/chip.ts: import the component and add it under the right Chip.<Category> key.
5. Export the category from src/index.ts if you added a new category folder (existing categories already use export * from "./chips/..."). Test chips stay on the react-visual-chips/test entry only (not the root barrel).
6. Add a Vite lib entry in vite.config.ts and a matching package.json "exports" block only if you introduce a new top-level category entry file (follow existing banking, generic, ... pattern).

Registry: chipRegistry.test.ts asserts listChips() matches every component registered on Chip -- if you add a chip to exports but forget chip.ts, tests will fail.

Smoke tests: chips.test.tsx renders every registered chip and asserts it produces an <svg> with a viewBox.

Tests & CI

npm test          # vitest
npm run build     # Vite library build
npm run lint      # ESLint
npm run format    # Prettier

CI runs the same on push/PR (see .github/workflows/ci.yml).

Code style

• ESLint (@typescript-eslint + react-hooks) and Prettier are configured. Run npm run lint and npm run format.
• Match existing TypeScript strictness, imports, and component patterns.
• Prefer small, focused changes; avoid unrelated refactors in the same PR.
• Use useSvgId(prefix) instead of useId().replace(...) for SVG-safe unique ids.
• Use polyline, polygon, or svgPath() instead of raw d string literals.
• New color behavior should go through resolveChipColor / useChipDesign where possible so colorMode stays consistent.

Legal / brands

Brand-inspired artwork (e.g. payment marks) should stay clearly non-official in comments and naming where applicable; respect third-party trademark guidelines.

License

MIT -- see package.json.