Getting started

Installation & Setup

Get StateGlyph running in your project in under a minute. Works with any React 18+ environment.

Install the React package

Choose your package manager:

npmnpm install @stateglyph/react

yarnyarn add @stateglyph/react

pnpmpnpm add @stateglyph/react

Peer dependencies

@stateglyph/react requires react ≥ 18 and lucide-react. Both are listed as peer dependencies and will be installed automatically with most package managers.

Basic usage

Import from the main package or from a specific icon path for better tree-shaking:

Main import

import { UploadStateIcon } from "@stateglyph/react";
export function UploadButton() {  return <UploadStateIcon state="idle" />;}

Direct import

// Import only the icon you need (better tree-shaking)import { UploadStateIcon } from "@stateglyph/react/upload";

Framework setup

NNext.js

If you're using Next.js with the App Router, add the StateGlyph packages to transpilePackages so they compile correctly:

next.config.ts

// next.config.tsimport type { NextConfig } from "next";
const nextConfig: NextConfig = {  transpilePackages: [    "@stateglyph/core",    "@stateglyph/react",  ],};
export default nextConfig;

VVite

Vite works out of the box. No configuration needed — just install and import. StateGlyph ships ESM and is fully tree-shakeable.

Accessibility

StateGlyph icons are decorative by default (aria-hidden="true"). When an icon communicates information not already conveyed by nearby text, set decorative={false} and optionally provide a custom label:

Decorative vs. semantic

// Decorative (default) — hidden from screen readers<UploadStateIcon state="loading" />
// Semantic — announced by screen readers<UploadStateIcon  state="success"  decorative={false}  label="Upload complete"/>

Alternative: Copy with the CLI

Prefer to own the source code? The CLI copies editable component files into your project. Generated components require react and lucide-react in the receiving project.

Terminal

# List available iconsnpx @stateglyph/cli list
# Add a single iconnpx @stateglyph/cli add upload
# Add to a custom directorynpx @stateglyph/cli add upload --dir src/components/icons
# Add all iconsnpx @stateglyph/cli add all

See the CLI Reference → for all options.

TypeScript

StateGlyph ships full TypeScript definitions. Every icon component exports its own prop type (e.g. UploadStateIconProps) with a typed state prop. No @types package needed.

Check the API Reference → for all exported types.