@molecule/app-icons

Framework-agnostic icon set interfaces for molecule.dev.

Icon set bond packages (e.g. @molecule/app-icons-molecule) export an IconSet object which is bonded via {@link setIconSet} at application startup. Application code retrieves icons via {@link getIcon} / {@link getIconDataUrl}, both of which call {@link getIconSet} internally.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { setIconSet, getIconDataUrl } from '@molecule/app-icons'
import { iconSet } from '@molecule/app-icons-molecule'

setIconSet(iconSet) // once, at app startup — before anything renders an icon

// In components, prefer your framework UI's Icon component
// (e.g. <Icon name="check-circle" /> from the app's UI bundle), which reads
// the bonded set. For CSS/background/favicon contexts:
const url = getIconDataUrl('check-circle', '#16a34a')

Type

core

Installation

npm install @molecule/app-icons @molecule/app-bond @molecule/app-i18n

API

Interfaces

IconPath

Single SVG path element data.

interface IconPath {
  d: string
  fill?: string
  fillRule?: 'evenodd' | 'nonzero'
  clipRule?: 'evenodd' | 'nonzero'
  opacity?: number
}

IconData

Complete icon definition — framework-agnostic SVG data.

interface IconData {
  /** SVG path elements. */
  paths: IconPath[]
  /** viewBox attribute. Default: "0 0 20 20" */
  viewBox?: string
  /** fill attribute. Default: "currentColor" */
  fill?: string
  /** stroke attribute (for outlined icons). */
  stroke?: string
  /** strokeWidth for outlined icons. */
  strokeWidth?: number
  /** strokeLinecap for outlined icons. */
  strokeLinecap?: 'round' | 'butt' | 'square'
  /** strokeLinejoin for outlined icons. */
  strokeLinejoin?: 'round' | 'miter' | 'bevel'
  /** Raw inner SVG content for complex icons that can't be represented as paths alone. */
  svg?: string
}

IconSet

A named set of icons.

interface IconSet {
  [name: string]: IconData
}

CustomIconNames

Augmentable registry of extra icon names beyond {@link ComponentIconName}.

An icon set bond (or an app merging custom glyphs into the bonded set) that provides names beyond the required contract declares them here so getIcon() / <Icon name="…" /> accept them type-safely:

declare module '@molecule/app-icons' {
  interface CustomIconNames {
    'my-custom-glyph': true
  }
}

Keys are icon names; values are always true (the interface is a name registry, never instantiated).

interface CustomIconNames {}

Types

IconName

Every icon name known to the type system: the {@link ComponentIconName} contract every icon set must provide, plus any {@link CustomIconNames} augmentations. Use this for getIcon() arguments and icon/name props so a typo fails the type-check instead of throwing at render time.

type IconName = ComponentIconName | (keyof CustomIconNames & string)

ComponentIconName

Icons required by UI components. All icon set providers MUST include these.

type ComponentIconName =
  // Status
  | 'info-circle'
  | 'check-circle'
  | 'exclamation-triangle'
  | 'x-circle'
  // Close/dismiss
  | 'x-mark'
  // Navigation arrows
  | 'arrow-left'
  | 'arrow-right'
  | 'arrow-up'
  | 'arrow-down'
  // Chevrons
  | 'chevron-left'
  | 'chevron-right'
  | 'chevron-up'
  | 'chevron-down'
  | 'chevrons-left'
  | 'chevrons-right'
  | 'chevrons-up-down'
  // Common actions
  | 'search'
  | 'plus'
  | 'minus'
  | 'check'
  | 'pencil'
  | 'trash'
  | 'copy'
  | 'download'
  | 'upload'
  | 'share'
  | 'link'
  | 'link-external'
  | 'filter'
  | 'sort-asc'
  | 'sort-desc'
  | 'sync'
  // UI controls
  | 'ellipsis-horizontal'
  | 'eye'
  | 'eye-closed'
  | 'gear'
  | 'lock'
  | 'unlock'
  | 'home'
  | 'globe'
  | 'menu'
  | 'maximize'
  | 'minimize'
  // User
  | 'user'
  | 'people'
  | 'sign-in'
  | 'sign-out'
  // Theme
  | 'sun'
  | 'moon'
  // Notifications
  | 'bell'
  // Content
  | 'file'
  | 'folder'
  | 'calendar'
  | 'clock'
  | 'history'
  | 'tag'
  | 'star'
  | 'heart'
  | 'code'
  | 'mail'
  // Misc
  | 'bug'
  | 'lightbulb'
  | 'mention'
  | 'microphone'
  | 'paperclip'
  | 'question'
  | 'bookmark'
  | 'pin'
  | 'reply'
  | 'image'
  | 'table'
  | 'thumbsup'
  | 'thumbsdown'
  // Brand
  | 'logo-mark'
  | 'logo-dot'
  | 'github'
  | 'google'
  | 'gitlab'
  | 'twitter'

Functions

setIconSet(iconSet)

Registers an icon set as the active singleton. Called at application startup to wire an icon library.

function setIconSet(iconSet: IconSet): void

• iconSet — The icon set (a record of icon names to icon data).

getIconSet()

Retrieves the bonded icon set, throwing if none is configured.

function getIconSet(): IconSet

Returns: The bonded icon set.

hasIconSet()

Checks whether an icon set is currently bonded.

function hasIconSet(): boolean

Returns: true if an icon set is bonded.

getIcon(name)

Retrieves a single icon by name from the bonded icon set.

function getIcon(name: IconName): IconData

• name — The icon name to look up.

Returns: The icon data (paths, viewBox, stroke/fill attributes).

getIconDataUrl(name, color)

Generates a CSS url() data URI containing an inline SVG for an icon. Useful for backgroundImage styling of native elements (e.g. <select> dropdown arrows) where SVG elements cannot be inserted.

function getIconDataUrl(name: IconName, color?: string): string

• name — The icon name to render.
• color — The stroke/fill color for the SVG (defaults to '#6b7280').

Returns: A CSS url("data:image/svg+xml,...") string.

Available Providers

| Provider | Package | | -------- | ------------------------------ | | Molecule | @molecule/app-icons-molecule |

Injection Notes

Requirements

Peer dependencies:

• @molecule/app-bond ^1.0.1
• @molecule/app-i18n ^1.0.1

Runtime Dependencies

• @molecule/app-bond

• @molecule/app-i18n

• Bond the icon set before first render — getIcon()/getIconDataUrl() (and any Icon component built on them) throw until setIconSet() has run; wire it in the app's bond setup, not lazily inside a component.

• Icon names are kebab-case ('arrow-right', 'x-mark') and type-checked against IconName. Don't invent names: an unknown name is a runtime error, not a blank. App-specific glyphs are added by merging IconData into the bonded set and augmenting CustomIconNames (see that interface) — never by inlining raw SVG per call site.

• Icons are decorative by default — pair them with accessible text (t('key', values, { defaultValue }) labels or aria-label), never as the only carrier of meaning.

Translations

Translation strings are provided by @molecule/app-locales-icons.