Pricing

Icon handbook

v2.3.4 · @snowui-design-system/components

License: Before reading component documentation, source, or npm usage instructions for the first time, read the full LICENSE. Reuse that review for the same task and version. Public API configuration and internal implementation changes have different license implications. All components use the unified runtime package; source rights remain governed by the license.

Overview

Display SVG icons with consistent size and color in buttons, navigation, and content.

When to use it

Use Icon as a consistent host for icons and sizing. Prefer SnowUI resource icons. For an action, place Icon inside Button and give the button an accessible name.

  • Prefer resource icons. Render children only when neither src nor a resolved icon is available.

  • Size can inherit the parent size; the corner label uses Badge as="badge". The interaction name should be provided to the button that owns the operation.

  • The Icon as="leading" in Accordion inherits the Accordion icon size when size is not explicitly specified: sm/md/lg are 16/20/24 respectively; Icon that does not declare leading does not participate in this inheritance, and the explicit size takes precedence.

Quick start

This example shows the recommended basic composition. See the sections below for more cases and composition limits.

<script lang="ts">	import { Icon } from '@snowui-design-system/components';	import { IconSet } from '@snowui-design-system/resource-svelte';	const sizes = [12, 16, 20, 24, 28, 32, 40, 48, 80] as const;</script> <div style="display: flex; flex-wrap: wrap; align-items: center; justify-content: center; gap: var(--gap-4) var(--gap-3); max-width: 100%;">{#each sizes as size}    <Icon icon={IconSet} {size} aria-label={`Component icon, size ${size}`} />{/each}</div>

API

Keyword Type Default Description
src string — Icon picture URL
icon Component<any> — Directly render the resource-svelte icon component.
stateIcon StateValueMap<Component<any> | null> — Resolve the icon from the nearest parent Frame’s currentState. Fall back to Idle, then to icon, src, or children.
size IconSize — Icon size. When not explicitly set, it automatically inherits the parent Frame to provide the size context.
background boolean false Whether to display the background
weight string — Visual weight passed to the icon resource: thin, light, regular, bold, fill, or duotone when supported. If omitted, the host context determines it.
as | "badge" | "icon" | "prev" | "next" | "close" | (string & {}) "icon" Role: as an independent icon, logo, picture center icon or Viewer control icon
children Snippet — The icon content is combined with the corner mark; it is rendered only when both src and the parsed icon are not hit; the resource icon and Badge as="badge" can be put in at the same time, and the corner mark is positioned by the host.
badgePosition "top" | "bottom" "top" The position as the host of the corner mark: top is the upper right, and the bottom is the lower right.

See the base component documentation for inherited capabilities not redeclared here. This table lists only named public Props declared by this component.

Usage boundaries and details

Layout model

Main layout model: internal atomic layout.

  • The root node of Icon is an inner box jointly determined by size, background padding and icon resources, which is expressed as Hug as other layout sub-items.

  • as="leading" / "trailing" / "icon" / "badge" / "prev" / "next" / "close" only declares the role of Icon in the external host; when entering the Image / ImageViewer host, it will be translated by the host context to the corresponding pin-* direction.

  • Background, empty space, badge overlay, and resource rendering are Icon’s private layout; Icon does not expose general slots.

  • When icons and text are required externally, the host components such as Button, MenuItem and Frame should be responsible for gap / padding / alignment.

stateIcon Parsing rules

  1. Icon reads the currentState of the recent parent Frame Context.

  2. Use this icon when the current state hits stateIcon[currentState].

  3. If the current state has no match, fall back to stateIcon.Idle.

  4. If still unresolved, use the normal icon, src, or children rule.

  5. Icon is hidden when the status value is null, which is used for stable structure state streams such as Idle without icon and Pending showing Spinner.

  6. stateIcon only affects the display of Icon itself and does not modify the parent Frame state.

Load is the status name of the Frame loading / skeleton protocol. If only the button task is being processed and the real Spinner needs to be displayed, Pending is preferred.

Usage examples

 <Icon src="/bell.svg" size={24} />  <Icon size={24}>    <Bell /></Icon>  <Icon background class="bg-black-4">    <Bell size={48} weight="duotone" /></Icon>  <Icon size={32} background class="bg-black-4">    <Badge as="badge" dot />    <Bell /></Icon>  <Button Click="Active" Active={["Idle", "auto"]} whileActive={{ duration: 2000 }}>    <Icon stateIcon={{ Idle: Paperclip, Active: Check }} />    <Text stateText={{ Idle: "Copy", Active: "Copied" }} /></Button>  <Button    Click={{ Idle: "Pending", Active: "Idle" }}    Pending={["Active", "auto"]}>    <Icon stateIcon={{ Idle: null, Pending: Spinner, Active: Check }} />    <Text stateText={{ Idle: "Ready", Pending: "Loading...", Active: "Completed" }} /></Button>  <Avatar size={40}>    <Icon as="badge" background class="bg-blue text-white">        <Check />    </Icon></Avatar>

Subcomponent context (Context)

Icon provides adaptive positioning context for subcomponents (such as Badge or another Icon):

  • badgeStyle: em-based absolute positioning keeps a badge aligned to the icon’s outer corner.

  • badgeSize: default dot size (0.25em).

- size and weight are passed down by Icon; an explicit child icon value takes precedence (not recommended).

Icon style overlay

Read the full LICENSE first; reuse that review for the same task, version, and scope.

First use public component Props to match the desired appearance, preserving the existing look where possible. If changes are necessary, follow the style selection and override order: use your own class (including Tailwind already in the project) or an instance style. The names below are public overrides actually consumed by source; check their scope and do not modify private DOM. Choose the correct SnowUI token family. External apps need not install SnowUI website utilities.

Variable Purpose and default reference
--snowui-accordion-icon-size-override Default expand/fold icon size (default sm 16 / md 20 / lg 24)
--snowui-button-icon-size-override Icon size (size px, see the component source code for the default value)
--snowui-icon-background-override Background (see component source for the default).
--snowui-icon-font-size-override font-size (see component source for the default).
--snowui-icon-font-weight-override Word weight (see the component source code for the default value)
--snowui-icon-height-override Height (see the component source code for the default value)
--snowui-icon-line-height-override line-height (see component source for the default).
--snowui-icon-min-height-override Minimum height (see the component source code for the default value)
--snowui-icon-min-width-override Minimum width (see the component source code for the default value)
--snowui-icon-padding-override padding y+x
--snowui-icon-radius-override border-radius
--snowui-icon-size-override Overall size (size px, see the component source code for the default value)
--snowui-icon-width-override Width (see the component source code for the default value)

Design Guide · Token · Combination Boundary

Icon type and status

Required Props: no named required Props.

Bindable Props: this component declares no named two-way binding; handle state updates through public callbacks or its host.

Inheritance: FrameProps. Consult the base class public documentation; fields excluded by Omit cannot be passed through unchanged.

Share Frame API · Return API

The following type declarations are actually referenced by public Props and come from source. A Svelte Snippet denotes a content fragment; ComponentProps denotes the Props of the corresponding component.

StateValueMap

Source: components/src/logic/frame-types.ts

export type StateValueMap<T = any> = Partial<Record<CoreState, T>>;

CoreState

Source: components/src/logic/frame-types.ts

export type CoreState =    | "StartLoad"    | "Load"    | "Reload"    | "Appear"    | "Disappear"    | "Idle"    | "Active"    | "Disabled"    | "Validating"    | "Uploading"    | "Editing"    | (string & {});

IconSize

Source: components/src/components/Icon.svelte

export type IconSize = 12 | 16 | 20 | 24 | 28 | 32 | 40 | 48 | 80;