Icons

Bits draw their icons from role tokens, so the icon library is swappable. Lucide is the default set, and it adds about 1 KB gzipped to @bitsyui/core.

Icons are tokens

Bits never name an icon library. They ask for an icon by its role, and the active icon set answers.

Roles

Each icon a Bit can draw is a token named for its job, such as --bitsy-icon-close. The list is short and only grows when a Bit needs a new role.

Sets

An icon set gives every role a glyph. Lucide is the default. A different set is one stylesheet that sets the same tokens, so you can change libraries without touching a Bit.

Rendering

Bits use the token as a CSS mask painted with the text color. Icons follow every variant, mode, and appearance, and size from --bitsy-icon-size (default 1em).

Icon roles

These are the roles in the current set. Each glyph renders from the live token, so it shows whichever set the page loads.

Token	Lucide name	Used for
`--bitsy-icon-chevron-down`	`chevron-down`	Opens a list or panel below: Select, Accordion, menu triggers
`--bitsy-icon-chevron-left`	`chevron-left`	Goes back or to the previous item: Pagination, Calendar. Flips in right-to-left layouts.
`--bitsy-icon-chevron-right`	`chevron-right`	Goes forward or deeper: Breadcrumb, Pagination, Calendar, submenus. Flips in right-to-left layouts.
`--bitsy-icon-check`	`check`	Selected or done: Checkbox, Combobox, Stepper
`--bitsy-icon-close`	`x`	Closes or removes: Dialog, Sheet, Toast, Alert, Badge
`--bitsy-icon-minus`	`minus`	Mixed state or decrease: Checkbox, Number Field
`--bitsy-icon-plus`	`plus`	Increase or add: Number Field
`--bitsy-icon-search`	`search`	Search fields: Input Group, Command Palette
`--bitsy-icon-info`	`info`	Neutral notice: Alert, Toast
`--bitsy-icon-success`	`circle-check`	Success notice: Alert, Toast
`--bitsy-icon-warning`	`triangle-alert`	Warning notice: Alert, Toast
`--bitsy-icon-error`	`circle-alert`	Error notice and field errors: Alert, Toast, fields
`--bitsy-icon-calendar`	`calendar`	Date entry: Date Picker
`--bitsy-icon-copy`	`copy`	Copy to clipboard: Code Block
`--bitsy-icon-upload`	`upload`	File selection: File Upload
`--bitsy-icon-more`	`ellipsis`	More actions or skipped pages: Menu triggers, Pagination

Swap icons

Swapping is a token override, the same way you recolor or reshape Bitsy.

One icon

Set the role token after @bitsyui/core. Every Bit that draws that role picks it up.

:root {
  --bitsy-icon-chevron-down: url("https://example.com/icons/caret-down.svg");
}

A whole set

Import a set file after core. A set file sets every --bitsy-icon-* role and nothing else.

@import "@bitsyui/core";
@import "./my-icon-set.css";

Rules for a set

Fill every role. A role without a glyph would draw a solid square, so the build checks every set Bitsy ships.
Use a data URI or an absolute URL. A relative URL inside a custom property may resolve against a different file than you expect.
Draw on a square viewBox with the glyph centered, so Bits can size icons from one token.
Keep the set's license notice with the CSS. Bitsy's default set ships Lucide's notice in icons.css.

Icon sets are separate from appearances and light or dark mode. A style pack can bring its own set.

Icons in your markup

For icons you place yourself, paste inline SVG from the same library. There is no runtime and no icon font.

<button type="button" data-bitsy-button>
  <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor"
       stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
    <path d="m21 21-4.34-4.34"/><circle cx="11" cy="11" r="8"/>
  </svg>
  Search
</button>

<button type="button" data-bitsy-button data-bitsy-shape="square" aria-label="Copy link">
  <svg aria-hidden="true" …>…</svg>
</button>

Use stroke="currentColor" or fill="currentColor" so the icon takes the text color, and leave out width and height. Bits size an svg placed inside them.

Accessibility and fallbacks

Icons are decorative. Mark your own icons aria-hidden="true". An icon-only control needs an aria-label. Bit-drawn icons never carry meaning alone, so swapping or losing one never changes what a screen reader says.
Forced colors. A mask is painted with a background color, which Windows forced colors overrides. Bits paint their icons with a system color in that mode, or hand drawing back to the native control.
Native fallbacks stay. Where an element has its own indicator, such as the select arrow or the details marker, it remains the fallback when a Bit removes its drawn icon.
Right to left. Bits flip chevron-left and chevron-right in right-to-left layouts. Other roles stay as drawn.

License

Bitsy is MIT licensed. The default icons come from Lucide (lucide-static 1.66.0), which is ISC licensed, and some of its glyphs derive from Feather, which is MIT licensed. Both notices ship in icons.css and in @bitsyui/core/THIRD_PARTY_NOTICES.md.

Display

Bitsy UI