One component, many states
Instead of importing separate icons for idle, loading, and success, you import one component and pass the state you need. The component knows which glyph to render.
Getting started
Guide
StateGlyph is an open-source collection of typed React icons that communicate what an interface is doing — not just what an action looks like.
What is a state icon?
Most icon libraries give you individual drawings — a cloud, an arrow, a checkmark. You then wire conditional rendering to swap between them as your UI changes. StateGlyph flips this: each component groups the related visual states of an interface action into a single import.
A button that uploads a file moves through idle → loading → success → error. With StateGlyph, you pass state="loading" and the right icon appears — typed, labelled, and accessible.
upload-button.tsx
import { UploadStateIcon } from "@stateglyph/react";
function UploadButton({ status }) { return ( <button> <UploadStateIcon state={status} size={20} /> Upload file </button> );}Core concepts
Typed state prop
Every icon component accepts a state prop that is a TypeScript string literal union. Pass an invalid state and you'll get a type error at build time — no runtime surprises.
Accessible by default
Each state carries an ARIA label and role. Icons are decorative by default. Set decorative={false} and screen readers announce the current state automatically.
Presentational only
StateGlyph renders state — it never owns your async logic, timers, or business rules. You remain in full control of when and how state changes.
Packages
StateGlyph is published as a monorepo with four packages. Most projects only need the React package.
@stateglyph/reactReady-to-use React components. Import, pass state, done.
@stateglyph/coreFramework-independent icon definitions, metadata, and TypeScript types.
@stateglyph/cliCopy-and-own component generator. Copies editable source into your project.
@stateglyph/transitionsOptional CSS transitions with reduced-motion support.