Reference

API Reference

Complete prop reference for StateGlyph React components and the underlying TypeScript types from @stateglyph/core.

Icon components

StateGlyph ships 31 pre-built icon components. Each accepts the same common props — the only difference is the typed state union.

Example usage

import { UploadStateIcon } from "@stateglyph/react";
<UploadStateIcon  state="loading"  size={24}  strokeWidth={2}  decorative={false}  label="Uploading file"  className="text-blue-500"/>

Common props

Every icon component accepts these props. All SVG props (className, style, onClick, etc.) are also forwarded to the root <svg> element.

Prop	Type	Default	Description
`state`*	string literal union	—	The current visual state. Each icon component types this as a union of its valid states (e.g. "idle" \| "loading" \| "success" \| "error").
`size`	number \| string	24	Width and height of the icon in pixels. Accepts a number or a CSS-compatible string.
`strokeWidth`	number	2	SVG stroke width. Lower values produce thinner lines. StateGlyph docs use 1.65.
`decorative`	boolean	true	When true (default), the icon is hidden from screen readers via aria-hidden. Set to false when the icon conveys meaning not present in surrounding text.
`label`	string	state label	Custom accessible label. Only used when decorative is false. Falls back to the label defined in the icon's state definition.
`className`	string	—	Additional CSS class names applied to the SVG element.

* required

Generic `StateIcon`

The base component that all icon components use internally. Useful if you want to pass an icon definition dynamically:

StateIcon usage

import { StateIcon } from "@stateglyph/react";import { uploadStateIcon } from "@stateglyph/core";
// Use the generic StateIcon with any icon definition<StateIcon  definition={uploadStateIcon}  state="idle"  size={24}/>

StateIcon accepts an additional definition prop — the icon definition object from @stateglyph/core. All common props above also apply.

Data attributes

Every rendered SVG includes data attributes for styling and testing:

Attribute	Example value	Description
data-state-icon	"upload"	The icon definition ID.
data-state	"loading"	The current state value.

Use these in CSS selectors ([data-state="loading"]) or test assertions.

Core types

The @stateglyph/core package exports the following types:

Type imports

import type { UploadStateIconProps } from "@stateglyph/react";import type {  StateIconDefinition,  StateIconStates,  StateIconStateDefinition,  StateIconSource,  StateIconLibrary,  StateIconCategory,  StateIconTransition,} from "@stateglyph/core";

`StateIconDefinition`

The shape of every icon definition in @stateglyph/core:

Field	Type	Description
id	string	Unique kebab-case identifier, e.g. "upload".
title	string	Human-readable title shown in documentation.
description	string	Short description of what the icon represents.
category	StateIconCategory	One of "async", "media", "navigation", "feedback", "device", "form", "commerce", or "notification".
states	Record<string, StateIconStateDefinition>	Map of state name to its icon glyph, label, description, and continuous flag.
initialState	keyof States	Which state the icon starts in.
transition	StateIconTransition	Transition hint — "crossfade", "scale-fade", "rotate", "slide", or "morph".
tags	readonly string[]	Searchable keywords for discovery.
source	StateIconSource	Source library metadata (extensible library name, license, URL, and icon names used).

See individual icon pages for the complete state definitions: Browse all icons →