Icon

An original linear icon set that renders inline SVGs by name; tree-shakable.

Usage

Common icons

Example

Size & color

Size & color

Example

Accessible name

Setting label exposes a readable name to screen readers.

Icons with labels

Example

Rotation & flipping

The spin attribute spins the icon infinitely (great for loading states); rotate rotates by a fixed angle; flip mirrors it (combinable with rotate).

spin

Example

rotate

Example

flip

Example

Custom icons

Four channels (pick by scenario):

• slot: put an inline <svg> inside the tag; it takes priority over name — one-off custom usage
• src: fetch a local or CORS-enabled SVG URL and render it inline (color follows color / currentColor) — your own SVG assets
• registerIcon(name, svg): register once, then use via name (same-name overrides built-ins) — the proper path for app-level custom icon sets
• registerIconLibrary: hook up a whole remote icon library (resolver → URL fetched on demand, sprite supported) — external icon libraries

⚠️ The built-in icon set is opt-in: the full entry @oas-ui/ui registers it automatically; per-component imports that use a built-in icon name (<oas-icon name="close">, etc.) need a one-time import '@oas-ui/icons/register'. Do not mutate the built-in icon data (the internal structure exported by @oas-ui/icons/registry, with no override/cleanup semantics); the proper path is registerIcon() / registerIconLibrary() (official API, pure function, SSR-safe).

Want zero inline tax with out-of-the-box names? Use registerIconLibrary(name, { resolver, spriteSheet }) to hook up a remote / sprite icon library — icons are referenced via <use> or fetched on demand and never inlined into the bundle (see "Remote icon library" below); or ship your own set via registerIcon(name, svg).

src SVG

Example

slot inline SVG (takes priority over name)

Example

Icon library registration

registerIcon(name, svg) registers a custom icon for reuse by name (overriding built-in icons with the same name).

registerIcon custom icons

Example

Remote icon libraries

registerIconLibrary(name, { resolver, mutator, spriteSheet }) registers a remote icon library: resolver maps an icon name to an SVG URL, which the component fetches on demand and inlines (color follows color / currentColor); mutator adjusts the SVG after inlining (e.g. restoring stroke="currentColor" for outline icons); spriteSheet renders <use href="url#name"> instead of inlining the whole SVG.

CDN library (Lucide via jsDelivr, mutator for outline icons)

Example

Local sprite sheet (<use> reference)

Example

family variants (local demo-set)

Example

variant (e.g. stroke weight)

Example

Icon font (iconfont)

iconfont-url injects an iconfont project script (symbol sprite JS): the component appends the <script> on demand, de-duplicates by URL, and re-renders all consumers once it loads, inlining the project's <symbol> content into the component (a #fragment cannot cross Shadow DOM boundaries, so <use> is not used).

registerIconAlias(alias, target) registers aliases (including prefix aliases) mapping short names to project symbol names: after registerIconAlias('i-', 'icon-'), name="i-star" resolves to icon-star.

iconfont project script + alias prefix

Example

Animation presets

The animation attribute provides ready-to-use animations (respecting prefers-reduced-motion).

Animation presets

Example

Duotone

duotone colors icon layers separately: data-layer="primary" / data-layer="secondary" (or the first two shape elements) are tinted with --oas-icon-primary-color / --oas-icon-secondary-color, with default opacity 1 / 0.4 (overridable on the host). swap-opacity swaps the two opacities. Built-in icons are monochrome, so this is mainly for custom two-layer SVGs.

Duotone

Example

Canvas modes

canvas controls the icon placeholder box: fixed (1.25×1em) / auto (natural width × 1em) / square (1.25×1.25em) / roomy (1.5×1.5em); an explicit size wins.

Canvas modes

fixed

auto

square

roomy

Example

Depth

depth controls opacity levels (1=100% … 5=20%), useful for creating hierarchy in icon groups.

Depth

Example

On-demand import

import { checkPath } from '@oas-ui/icons'
import { registerIcon } from '@oas-ui/ui'

registerIcon('my-icon', '<path d="..."/>')

Icon gallery

All icons (click to copy name)

Example

API

oas-icon

Attributes

Attribute	Description	Type	Default
animation	Animation presets: spin / spin-pulse / spin-reverse / spin-snap / beat / fade / beat-fade / bounce / shake / swing / wag / buzz / float / jello (respects prefers-reduced-motion)	string	—
canvas	Canvas mode: fixed (default 1.25×1em) / auto (natural width × 1em) / square (1.25×1.25em) / roomy (1.5×1.5em)	string	—
color	Color (CSS value)	string	—
depth	Opacity depth level: 1 (100%) ~ 5 (20%), for layered icon hierarchy	string	—
duotone	Duotone icon: layered coloring (--oas-icon-primary-color / --oas-icon-secondary-color + opacity), mainly for custom dual-layer SVG	boolean	—
family	Icon family (passed to the library resolver, e.g. outline/filled)	string	—
flip	Flip mirror (x / y / both axes), combinable with rotate	string	—
iconfont-url	Remote iconfont project script URL: injected on demand, de-duplicated per URL, consumers re-render with the symbol inlined once loaded	string	—
label	Accessible name; sets role="img" when provided	string	—
library	Remote icon library name (registered via registerIconLibrary), takes precedence over the built-in name registry	string	—
name	Icon name (kebab-case)	string	—
rotate	Rotate by any angle (rotate="45" degrees)	string	—
size	Size (px or em)	string	—
spin	Spin animation: continuous rotation (loading)	boolean	—
src	Custom icon URL: remote/local SVG, fetched and inlined (color follows color / currentColor)	string	—
swap-opacity	Swap primary / secondary opacity of a duotone icon	boolean	—
variant	Icon variant (passed to the library resolver, e.g. weight)	string	—

Slots

Name	Description
default	Custom icon content (replaces the built-in icon)

CSS Variables

CSS Variable	Default
--oas-icon-primary-color	currentColor
--oas-icon-primary-opacity	1
--oas-icon-secondary-color	currentColor
--oas-icon-secondary-opacity	0.4

Icon names: alert-circle arrow-down arrow-left arrow-right arrow-up calendar check-circle check chevron-down chevron-left chevron-right chevron-up clock close-circle close copy download edit error external-link eye filter form gear heart info language loading lock mail menu minus more-vertical more organization plus refresh search sort star-filled star translate trash tree upload user warning.