API reference#

Every value and type exported from @sigx/lynx-icons.

The package entry re-exports three values — Icon, useIconColorResolver, defineIconSet — and a set of supporting types. All exports work on both iOS and Android.

Components#

Icon#

Renders a glyph from a registered icon set, addressed by set plus name. It resolves the glyph as SVG first, then by codepoint (font mode, reserved for v1.1), then falls back to an empty <view> of the same size so missing glyphs do not shift layout.

export const Icon = component<IconProps>(({ props }) => {
    // ...resolve color, look up glyph, render <svg>/<text>/<view>
});

Props are described under IconProps. Color is substituted into the SVG fill via a __COLOR__ placeholder, not via CSS inheritance. Resolution order for the color is: explicit props.color, then the active theme resolver's return (see useIconColorResolver), then 'currentColor'.

Platform: both.

Hooks#

useIconColorResolver#

An injectable holding the active theme's color resolver, or null. Themes provide one with defineProvide(useIconColorResolver, …) so <Icon> can map theme-augmented props (such as DaisyUI's variant) to a CSS color. The default resolver returns null.

export const useIconColorResolver = defineInjectable<IconColorResolver | null>(() => null)

The held value is an IconColorResolver or null.

Platform: both.

Functions#

defineIconSet#

Registers a custom icon set at module-load time. This is the runtime escape hatch for ad-hoc or app-local sets that are not declared in signalx.config.ts. It returns the same def it was given; as a side effect it registers the set internally.

export function defineIconSet(def: IconSetDef): IconSetDef

Parameters:

• def — an IconSetDef describing the set's id, glyphs, and optional fontFamily.

Returns: the same IconSetDef.

Runtime-registered sets are checked after the build-time maps, so they will not shadow glyphs produced by the build pipeline.

Platform: both.

Types#

IconProps#

The prop type for Icon. set and name are required; size, color, and class are optional. It is intersected with IconPropsExtensions so themes can add typed props.

export type IconProps =
    & Define.Prop<'set', string, true>
    & Define.Prop<'name', string, true>
    & Define.Prop<'size', number, false>
    & Define.Prop<'color', string, false>
    & Define.Prop<'scaleWithText', boolean, false>
    & Define.Prop<'class', string, false>
    & IconPropsExtensions;

• set (required) — the icon set id, the value declared in signalx.config.ts or passed to defineIconSet.
• name (required) — the glyph name in the set's canonical kebab-case.
• size (optional) — pixel size, default 16.
• color (optional) — CSS color, default 'currentColor'; runs through an allow-list before substitution.
• scaleWithText (optional) — follow the OS text-size setting. Default false.
• class (optional) — class string applied to the host.

Icons and the OS text size#

By default an icon holds its designed size in dp regardless of the system font scale. That is the layout-stable choice, and the right one for chrome — tab bars, headers, list accessories — where a growing glyph would break the bar it sits in.

Set scaleWithText for icons sitting inline with scaling text, where holding still would look wrong next to text that grew. The glyph and its box then grow together by the effective scale, live, and both backends (SVG and font mode) behave identically.

<Icon set="lucide" name="settings" />                      {/* chrome: fixed 16dp */}
<Icon set="lucide" name="info" scaleWithText />            {/* inline with body text */}

Read the scale yourself with useFontScale() when a layout has to change shape rather than just grow.

IconColorResolver#

The function form held by useIconColorResolver. It receives the full <Icon> props (including any theme-augmented fields) and returns a CSS color to substitute into the SVG fill, or undefined to fall through to props.color / currentColor.

export type IconColorResolver = (
    props: Readonly<Record<string, unknown>>,
) => string | undefined;

IconPropsExtensions#

An empty declaration-merge augmentation point. Theme packages module-augment it to add typed <Icon> props. Without a theme there are no extra props, and <Icon variant=…> will not typecheck.

export interface IconPropsExtensions {}

Augment it from a theme like so:

declare module '@sigx/lynx-icons' {
  interface IconPropsExtensions {
    variant?: 'primary' | 'secondary' | 'accent';
  }
}

IconSpec#

A lightweight { set, name } data reference to an icon, passed to UI primitives that accept an icon (for example a tab screen icon). The receiver composes an <Icon> from it.

export interface IconSpec {
    readonly set: string;
    readonly name: string;
}

Example usage by a consuming primitive:

<Tabs.Screen icon={{ set: 'lucide', name: 'map' }}>

IconSetDef#

A runtime-registered icon set, the argument to defineIconSet.

export interface IconSetDef {
    id: string;
    glyphs: Record<string, { codepoint?: number; svg?: GlyphSvg }>;
    fontFamily?: string;
}

• id — the value of <Icon set=>.
• glyphs — map of glyph name to { codepoint?, svg? }.
• fontFamily (optional) — font family for font-mode rendering.

GlyphSvg#

Per-glyph vector data for SVG-mode rendering. svg is a complete <svg>…</svg> string with __COLOR__ placeholders where the user's color is substituted at render time.

export interface GlyphSvg {
    svg: string;
}

GlyphData#

The glyph data an adapter returns at build time: an optional codepoint (which enables font-mode subsetting) plus the required svg string with __COLOR__ placeholders.

export interface GlyphData {
    codepoint?: number;
    svg: string;
}

IconAdapter#

The build-time adapter contract implemented by packages such as @sigx/lynx-icons-fa-free and @sigx/lynx-icons-lucide, consumed by the plugin's icons slice via a default export.

export interface IconAdapter {
    styles: string[];
    getGlyph(style: string, name: string): GlyphData | null;
    getFontPath(style: string): string | null;
    listGlyphs(style: string): string[];
}

• styles — the supported style variants.
• getGlyph(style, name) — resolves a glyph by style and name; returns GlyphData or null if unknown.
• getFontPath(style) — returns the absolute TTF path for a style, or null for SVG-only adapters.
• listGlyphs(style) — enumerates every glyph name in a style, used for include: ['*'].

Platform: build-time (Node), not runtime.

Internal subpath modules#

Apps do not import these from the public TS API; the plugin aliases them at build time and populates them with only the glyphs your app references. They are listed here for completeness.

• @sigx/lynx-icons/__codepoints — { codepoints: CodepointMap }, where CodepointMap is Record<string, Record<string, number>> (set id to glyph name to unicode codepoint). Empty stub by default.
• @sigx/lynx-icons/__svgs — { svgs: SvgMap }, where SvgMap is Record<string, Record<string, GlyphSvg>> (set id to glyph name to GlyphSvg). Empty stub by default.
• @sigx/lynx-icons/__font-face.css — an empty CSS stub, no-op in v1.

CodepointMap and SvgMap are not re-exported from the package entry; they live in the package's internal ./types.

See also#

• Usage guide for practical recipes.
• Installation for native setup.