Installation

Catnip ships on Signicat’s internal GitLab npm registry and on Signicat’s CDN.

npm — For Signicat developers and CI with registry access. Use with a bundler (Vue, React, Vite, webpack). Packages are scoped @signicat/catnip-*.
CDN — For anyone with a browser: plain HTML, server-rendered apps, or teams without npm registry access. Production: static.signicat.com/catnip/. Development: static.signicat.dev/catnip/.

Packages are not on the public npm registry today. If you cannot configure the GitLab registry and authenticate, use the CDN — not npm install.

npm

Components

Install @signicat/catnip-components together with @signicat/catnip-css. Components inject their own shadow DOM styles, but they read --catnip-* design tokens (colors, typography, spacing, and so on) from the page. @signicat/catnip-css supplies those variables plus base styles and utilities — without it, components register but will not look correct.

bash

npm install @signicat/catnip-components @signicat/catnip-css
# or
pnpm add @signicat/catnip-components @signicat/catnip-css
# or
yarn add @signicat/catnip-components @signicat/catnip-css

Import both at your app entry point:

import "@signicat/catnip-components";
import "@signicat/catnip-css";

Peer dependencies: vue (when using Vue).

React

For React, add @signicat/catnip-components-react (see React); it depends on @signicat/catnip-components and registers custom elements when imported.

Package entry points

Entry	Import	Use case
Default	`@signicat/catnip-components`	Standard ESM/UMD; use with Vue, design tokens, etc.
FOUC prevention	`@signicat/catnip-components/foucPrevention.min.css`	Hides `catnip-*` elements until styles load; include before component CSS

Design Tokens

bash

npm install @signicat/catnip-design-tokens

Usually not needed separately if you already import @signicat/catnip-css — that package bundles design tokens. Install tokens on their own only when you want the CSS or JS token files without the full Catnip CSS bundle.

CSS Utilities

bash

npm install @signicat/catnip-css

Required alongside @signicat/catnip-components for correctly styled components (see Components). Also provides typography/spacing utilities, grid, and icons CSS.

Icons

bash

npm install @signicat/catnip-icons

Registry

Catnip packages are published to the Signicat GitLab npm registry only — they are not on npmjs.com or otherwise publicly installable without Signicat credentials.

Inside Signicat (apps, CI, developers with access), configure npm and authenticate:

bash

npm config set @signicat:registry https://gitlab.com/api/v4/projects/75004529/packages/npm/

For authenticated access, use a GitLab personal access token or CI_JOB_TOKEN in CI.

Outside Signicat (or without registry access), you cannot run npm install @signicat/catnip-*. Use the CDN instead — every release mirrors dist/ to static.signicat.com/catnip/ (and static.signicat.dev/catnip/ for dev).

Public npm planned

Publishing to the public npm registry is planned for the future. When that happens, external teams may also use npm install; until then, CDN is the supported path without GitLab access.

CDN

Every @signicat/catnip-* package is mirrored to the CDN on each release. Load stylesheets with <link> tags. For components without a bundler, use the standalone IIFE (one script tag). The ES build is also on the CDN for advanced setups with an import map.

CDN hosts and URL pattern

Environment	Base URL
Production	`https://static.signicat.com/catnip/`
Development	`https://static.signicat.dev/catnip/`

Each package is deployed under its monorepo folder name:

{base}{package}/{version}/{file}
{base}{package}/latest/{file}

Examples (production):

https://static.signicat.com/catnip/components/latest/catnip-components.standalone.js
https://static.signicat.com/catnip/css/0.0.11/styles.css
https://static.signicat.com/catnip/icons/latest/catnip-icons.min.css

Path segment	Package	npm name
`components/`	Web Components	`@signicat/catnip-components`
`components-react/`	React wrappers	`@signicat/catnip-components-react`
`css/`	Base styles and utilities	`@signicat/catnip-css`
`design-tokens/`	CSS variables and JS tokens	`@signicat/catnip-design-tokens`
`icons/`	Icon webfont and SVG map	`@signicat/catnip-icons`
`assets/`	Fonts, illustrations, flags, logos	`@signicat/catnip-assets`

Versioned vs latest

{package}/{version}/ — immutable for that release. Prefer this in production so upgrades are explicit.
{package}/latest/ — always points at the newest release. Convenient for prototypes; pin a version when you ship.

Components

The standalone IIFE bundles Vue, all catnip-* custom elements, and lazy-loaded icon/illustration SVG maps. You do not need npm, a bundler, a separate Vue import, or an import map.

catnip-components.standalone.js is not on npm (it is built in CI and deployed to the CDN only). The ES/UMD builds on npm expect a bundler.

html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <!-- Design tokens + utilities (required for styled components) -->
    <link rel="stylesheet" href="https://static.signicat.com/catnip/design-tokens/latest/css/default.css" />
    <link rel="stylesheet" href="https://static.signicat.com/catnip/icons/latest/catnip-icons.min.css" />
    <link rel="stylesheet" href="https://static.signicat.com/catnip/css/latest/styles.css" />
    <!-- Optional: hide catnip-* tags until component styles are injected -->
    <link
      rel="stylesheet"
      href="https://static.signicat.com/catnip/components/latest/foucPrevention.min.css"
    />
  </head>
  <body>
    <catnip-button appearance="primary">Save</catnip-button>
    <catnip-icon name="tick" size="32"></catnip-icon>

    <script
      src="https://static.signicat.com/catnip/components/latest/catnip-components.standalone.js"
      defer
    ></script>
  </body>
</html>

Script tag, not module

The standalone build is an IIFE assigned to the global CatnipComponents. Use a classic <script src="…" defer> — not type="module".

The standalone script injects component styles (layout, states, and so on). You still need @signicat/catnip-css on the page (via the <link> tags above) so --catnip-* tokens resolve — see CSS, tokens, and icons — CDN.

Versioned URLs (EndUI-style)

Pin a release the same way EndUI did with version in the path:

html

<script
  src="https://static.signicat.dev/catnip/components/0.0.31/catnip-components.standalone.js"
  defer
></script>

Use latest/ only for prototypes; ship with {version}/ in production.

Why not `catnip-components.umd.js` with one script tag?

Catnip also publishes catnip-components.es.js and catnip-components.umd.js on the CDN (same files as npm). A single script tag like EndUI’s endui-components.umd.js is not equivalent today:

File	One `<script>`	Notes
`catnip-components.standalone.js`	✅ Recommended	IIFE; Vue + icon/illustration maps inlined
`catnip-components.umd.js`	⚠️ Partial	Classic `<script defer>` (not `type="module"`); still expects externals for some SVG maps
`catnip-components.es.js`	❌ Incomplete alone	Registers many components, but `catnip-icon` / `catnip-graphic` need an import map

EndUI’s bundle was self-contained under one URL. Catnip’s standalone build is the same idea; umd.js / es.js are the slimmer npm-oriented builds.

Advanced: ES module + import map

If you prefer catnip-components.es.js, map lazy SVG entry points with an import map (Vue is already bundled in the ES file):

html

<script type="importmap">
  {
    "imports": {
      "@signicat/catnip-icons/svg": "https://static.signicat.com/catnip/icons/latest/svg-map.mjs",
      "@signicat/catnip-assets/illustrations/svg": "https://static.signicat.com/catnip/assets/latest/illustrations-svg.mjs",
      "@signicat/catnip-assets/countries/flags/svg": "https://static.signicat.com/catnip/assets/latest/country-flags-svg.mjs"
    }
  }
</script>
<script type="module" src="https://static.signicat.com/catnip/components/latest/catnip-components.es.js"></script>

Pin versioned CDN URLs in production. Without the import map, catnip-icon and catnip-graphic fail at runtime when they load SVG chunks.

CSS, tokens, and icons

Required with components — load @signicat/catnip-css (and its dependencies) so --catnip-* tokens are defined on the page. Components read these variables; the standalone script does not replace this CSS.

Because npm-style @import paths inside styles.css do not resolve in the browser, load these files as separate <link> tags (in this order):

html

<link rel="stylesheet" href="https://static.signicat.com/catnip/design-tokens/latest/css/default.css" />
<link rel="stylesheet" href="https://static.signicat.com/catnip/icons/latest/catnip-icons.min.css" />
<link rel="stylesheet" href="https://static.signicat.com/catnip/css/latest/styles.css" />

Optional extras from the same CDN base:

Need	File
Dark semantic colors	`design-tokens/latest/css/dark.css` + `data-theme="dark"` — see Theming — CDN
Global reset	`css/latest/global-reset.css` (load before `styles.css`)
Bootstrap grid	`css/latest/bs-grid.css`

See also CSS overview — CDN for how this maps to optional modules.

Assets and fonts

styles.css references Inter through paths meant for bundlers. On CDN, point @font-face at the assets package:

html

<style>
  @font-face {
    font-family: "Inter";
    font-style: normal;
    font-weight: 100 900;
    font-display: swap;
    src: url("https://static.signicat.com/catnip/assets/latest/fonts/inter/Inter-VariableFont_opsz,wght.ttf")
      format("truetype-variations");
  }
  @font-face {
    font-family: "Inter";
    font-style: italic;
    font-weight: 100 900;
    font-display: swap;
    src: url("https://static.signicat.com/catnip/assets/latest/fonts/inter/Inter-Italic-VariableFont_opsz,wght.ttf")
      format("truetype-variations");
  }
</style>

Illustrations, flags, and pictograms are under assets/latest/… — see Assets overview — CDN.

Configuration

With the standalone bundle, use the global CatnipComponents object:

html

<script src="https://static.signicat.com/catnip/components/latest/catnip-components.standalone.js" defer></script>
<script>
  CatnipComponents.CatnipConfig.configure({
    automaticTypeConversion: true,
    nativeFormBehaviour: true
  });

  CatnipComponents.registerTranslate((key) => myTranslations[key] ?? key);
</script>

With the ES build and import map, use named exports in a module script — see Configuration — CDN.

Package file reference

`@signicat/catnip-components` → `components/`

File	Purpose
`catnip-components.standalone.js`	CDN-only IIFE — recommended without a bundler
`catnip-components.es.js`	ESM build (CDN: needs import map for SVG maps; npm: use with bundler)
`catnip-components.umd.js`	UMD build (needs bundler or global `Vue`)
`foucPrevention.min.css`	Hide `catnip-*` until styles load
`style.css`	Component stylesheet (usually not needed with standalone)
`custom-elements.json`	Custom Elements Manifest for tooling

`@signicat/catnip-css` → `css/`

File	Purpose
`styles.css`	Main bundle (tokens, typography, spacing, shadows)
`global-reset.css`	Optional CSS reset
`bs-grid.css`	Optional Bootstrap grid

`@signicat/catnip-design-tokens` → `design-tokens/`

File	Purpose
`css/default.css`	Light theme CSS variables on `:root`
`css/dark.css`	Dark semantic overrides (with `data-theme="dark"`)
`js/default.js` / `js/dark.js`	Token objects for JavaScript

`@signicat/catnip-icons` → `icons/`

File	Purpose
`catnip-icons.min.css`	Icon webfont (required for `catnip-icon--*` classes)
`catnip-icons.woff2`	Font file (referenced by the CSS)
`svg-map.mjs`	Lazy SVG map (inlined in standalone; external in ES build)

`@signicat/catnip-assets` → `assets/`

Path	Purpose
`fonts/inter/…`	Inter variable font files
`illustrations-svg.mjs`	Lazy illustration map for `catnip-graphic`
`country-flags-svg.mjs`	Lazy flag SVG map
`illustrations/…`	Static SVG files
`countries/flags/…`	Country flag SVGs

CDN vs npm

	CDN (standalone)	npm + bundler
Setup	`<script defer>` + optional `<link>`	`npm install` + `import`
Vue	Bundled in standalone	Peer dependency
Icon / illustration chunks	Inlined in standalone	Lazy-loaded via bundler
TypeScript	No types from CDN	Full types from packages
React	Use `@signicat/catnip-components-react` via npm	Recommended path

Self-hosting

CI builds catnip-components.standalone.js with pnpm run build:standalone (after pnpm build) and uploads every package’s dist/ to GCS. You can copy dist/ from a release and serve it from your own static bucket — keep the same relative paths if you mirror multiple packages (so icon font URLs in catnip-icons.min.css keep working).

Next Steps

Quickstart — Use your first component
Theming — Add light/dark themes
Components — Explore all components

Migration

CSS

Inputs

Installation

npm

Components

React

Package entry points

Design Tokens

CSS Utilities

Icons

Registry

CDN

CDN hosts and URL pattern

Components

Versioned URLs (EndUI-style)

Why not `catnip-components.umd.js` with one script tag?

Advanced: ES module + import map

CSS, tokens, and icons

Assets and fonts

Configuration

Package file reference

`@signicat/catnip-components` → `components/`

`@signicat/catnip-css` → `css/`

`@signicat/catnip-design-tokens` → `design-tokens/`

`@signicat/catnip-icons` → `icons/`

`@signicat/catnip-assets` → `assets/`

CDN vs npm

Self-hosting

Next Steps

Installation ​

npm ​

Components ​

React ​

Package entry points ​

Design Tokens ​

CSS Utilities ​

Icons ​

Registry ​

CDN ​

CDN hosts and URL pattern ​

Components ​

Versioned URLs (EndUI-style) ​

Why not catnip-components.umd.js with one script tag? ​

Advanced: ES module + import map ​

CSS, tokens, and icons ​

Assets and fonts ​

Configuration ​

Package file reference ​

@signicat/catnip-components → components/ ​

@signicat/catnip-css → css/ ​

@signicat/catnip-design-tokens → design-tokens/ ​

@signicat/catnip-icons → icons/ ​

@signicat/catnip-assets → assets/ ​

CDN vs npm ​

Self-hosting ​

Next Steps ​

Installation

npm

Components

React

Package entry points

Design Tokens

CSS Utilities

Icons

Registry

CDN

CDN hosts and URL pattern

Components

Versioned URLs (EndUI-style)

Why not `catnip-components.umd.js` with one script tag?

Advanced: ES module + import map

CSS, tokens, and icons

Assets and fonts

Configuration

Package file reference

`@signicat/catnip-components` → `components/`

`@signicat/catnip-css` → `css/`

`@signicat/catnip-design-tokens` → `design-tokens/`

`@signicat/catnip-icons` → `icons/`

`@signicat/catnip-assets` → `assets/`

CDN vs npm

Self-hosting

Next Steps