spectre-react-lib

Spectre.css and React integration

Requirements

• React and React DOM 18 or 19
• Spectre.css 0.5.9 styles, loaded by the consuming application

Installation

npm install spectre-react-lib spectre.css@0.5.9

spectre.css is an explicit external stylesheet dependency rather than a package peer dependency. This allows applications to use the npm package, a custom Sass build, or a CDN without package-manager conflicts. Version 0.5.9 is the currently tested CSS contract.

Stylesheets

This library does not inject global CSS. Import the layers your application uses, in this order:

// Required for stable/core components
import 'spectre.css/dist/spectre.min.css';

// Optional for Spectre icons
import 'spectre.css/dist/spectre-icons.min.css';

// Required in addition to core for experimental components
import 'spectre.css/dist/spectre-exp.min.css';

Applications using customized Sass or CDN styles should load the equivalent layers in the same order.

Usage

Stable components are exported from the package root:

import {
  Page,
  Pagination,
  Panel,
  Tab,
  Toast,
  Button,
  Table,
  Container,
  Grid,
  Divider,
  Loading,
  ControlledTab,
  EmptyState,
} from 'spectre-react-lib';

Core primitive examples

Use Container and Grid for canonical Spectre layout:

<Container size="lg">
  <Grid>
    <Grid.Column width={8} md={12}>
      Main content
    </Grid.Column>
    <Grid.Column width={4} md={12}>
      Sidebar
    </Grid.Column>
  </Grid>
</Container>

Buttons use exclusive variants and component-specific control sizes:

<Button variant="primary" controlSize="lg" loading={isSaving}>
  Save
</Button>

Tables expose semantic compound parts:

<Table striped hover scrollable>
  <Table.Caption>Accounts</Table.Caption>
  <Table.Head>
    <Table.Row>
      <Table.HeaderCell scope="col">Name</Table.HeaderCell>
      <Table.HeaderCell scope="col">Balance</Table.HeaderCell>
    </Table.Row>
  </Table.Head>
  <Table.Body>
    <Table.Row active>
      <Table.Cell>Ada</Table.Cell>
      <Table.Cell>$10</Table.Cell>
    </Table.Row>
  </Table.Body>
</Table>

Component parity examples

Controlled tabs support controlled or uncontrolled state, disabled options, orientation, and manual activation:

<ControlledTab
  options={tabs}
  value={activeTab}
  onValueChange={setActiveTab}
  activationMode="manual"
/>

Toasts use exclusive Spectre variants and opt-in live-region behavior:

<Toast variant="success" liveRegion="polite" onDismiss={dismissToast}>
  Changes saved.
</Toast>

See docs/migration-guide.md for compatibility APIs and deprecations.

Experimental components use a separate entrypoint:

import { Parallax } from 'spectre-react-lib/experimental';

Parallax supports canonical compound layers. Corner overlays enter the tab order only when their matching callback is supplied:

<Parallax>
  <Parallax.Content>
    <Parallax.Front>Foreground</Parallax.Front>
    <Parallax.Back>Background</Parallax.Back>
  </Parallax.Content>
</Parallax>

The existing root Parallax export remains available for backwards compatibility. The spectre-react-lib/icons boundary is reserved for the typed Icon component planned in the component coverage roadmap.

Storybook Examples

Click here to see the storybook examples.

Development

This project uses Bun for package management, scripts, and tests.

bun install
bun run ci

The supported CI and package-manager baseline is Bun 1.3.14, and local development may use the Bun 1.4 canary. Node.js 20.19+ is required.

Automated Releases

The CHANGELOG in this project is generated by Release Please. Release Please does this by parsing the git history, looking for Conventional Commit messages, and creating release PRs.