React

Use Catnip in React with @signicat/catnip-components-react: generated wrappers around the same catnip-* custom elements as everywhere else. Behaviour, props, slots, and events are defined by those elements.

API reference for each component (props, slots, events, examples) lives in the catalogue pages in this site — for example Button, Toggle, Chip. There is no separate React section on each page; this document covers framework wiring only.

Install

pnpm add react react-dom @signicat/catnip-components-react

@signicat/catnip-components is pulled in automatically as a dependency of the React package. Add it to your own package.json only if you want to pin its version or import other exports (CatnipConfig, vueModelDirective, etc.). Keep @signicat/catnip-components and @signicat/catnip-components-react on the same version when you pin (e.g. both 0.0.28).

Register custom elements

The first import from @signicat/catnip-components-react registers all catnip-* elements (equivalent to import "@signicat/catnip-components"). Import it from your app entry (or a layout) before rendering any Catnip UI.

Global styles

Include @signicat/catnip-css and any FOUC helper the same way as for non-React apps — see Installation and Components.

Wrappers

Import named components from the package:

import { CatnipToggle, CatnipButton } from "@signicat/catnip-components-react";

function Example() {
  const [on, setOn] = useState(false);
  return (
    <>
      <CatnipToggle
        modelValue={on}
        onUpdateModelValue={(e) => {
          const d = (e as CustomEvent).detail as unknown;
          setOn((Array.isArray(d) ? d[0] : d) as boolean);
        }}
      />
      <CatnipButton appearance="primary" size="m">
        Save
      </CatnipButton>
    </>
  );
}

Events

Vue emit names from the manifest are mapped to React props on + PascalCase (e.g. update:modelValue → onUpdateModelValue). Listeners receive the native CustomEvent. Payload shape is the same as for DOM usage — see Component API — Events.

Slots

Use normal React children; for named slots, put slot="…" on the child element, as in Component API — Slots.

Refs

Wrappers use forwardRef; the ref is the host custom element (HTMLElement).

TypeScript

The package augments JSX.IntrinsicElements for catnip-* tags and exports props types per component (e.g. CatnipToggleProps).

Where the wrappers come from

Wrappers are built from the Custom Elements Manifest (custom-elements.json) when @signicat/catnip-components-react is built. After changing Vue custom elements, publish or link updated @signicat/catnip-components, then rebuild the React package.

Monorepo playground

For local development, from packages/components-react:

pnpm run playground:dev

Ensure @signicat/catnip-css and @signicat/catnip-components have been built at least once. The playground is dev-only (Vite dev server), not published.

Without the React package

You can render catnip-* tags directly in JSX and use ref + addEventListener (especially for event names containing :). That workflow is summarised under Usage — React.