Quickstart

Get Catnip running in 5 minutes. Import both @signicat/catnip-components and @signicat/catnip-css — components need the CSS package for design tokens and appearance.

1. Install

npm (bundler or local static server)

Configure the Signicat GitLab registry, then:

npm install @signicat/catnip-components @signicat/catnip-css

In a micro-frontend, the shell installs and imports these packages once. Child apps do not install them — they render catnip-* tags and call window.Catnip for i18n, config, and helpers.

CDN (no npm, no bundler)

Load CSS and the standalone bundle from Signicat’s CDN (URL patterns in Installation — CDN):

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://static.signicat.com/catnip/css/latest/styles.css">
  <link rel="stylesheet" href="https://static.signicat.com/catnip/components/latest/foucPrevention.min.css">
</head>
<body>
  <catnip-button>Click me</catnip-button>
  <catnip-spinner size="48" type="default"></catnip-spinner>
  <script src="https://static.signicat.com/catnip/components/latest/catnip-components.standalone.js" defer></script>
</body>
</html>

2. Import

Vanilla HTML (npm)

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="node_modules/@signicat/catnip-css/dist/styles.npm.css" />
  <script type="module" src="node_modules/@signicat/catnip-components/dist/catnip-components.es.js"></script>
</head>
<body>
  <catnip-button>Click me</catnip-button>
  <catnip-spinner size="48" type="default"></catnip-spinner>
</body>
</html>

Vue 3

Tell the compiler catnip-* tags are custom elements. Vite (vite.config.ts):

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag.startsWith("catnip-")
        }
      }
    })
  ]
});

Nuxt: the same isCustomElement under vue.compilerOptions in nuxt.config.ts. Full copy-paste, TypeScript, and editor setup: Installation — Vue compiler.

<script setup>
import "@signicat/catnip-components";
import "@signicat/catnip-css";
</script>

<template>
  <catnip-button>Save</catnip-button>
  <catnip-icon name="user" size="24" />
</template>

For reactive / non-literal props use leading-dot camelCase (.modelValue, .disabled). Do not use v-model on catnip-* hosts. See Component API — Vue 3.

Bundler (Vite, webpack, etc.)

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

3. Use Components

<catnip-button appearance="primary">Primary</catnip-button>
<catnip-button appearance="secondary">Secondary</catnip-button>
<catnip-icon name="tick" size="32" />

4. TypeScript and editor hints

Add Catnip’s window.Catnip types in an env.d.ts:

/// <reference types="@signicat/catnip-components" />

For tag and attribute completion in HTML / Vue templates, point VS Code or Cursor at the generated HTML custom data:

{
  "html.customData": ["./node_modules/@signicat/catnip-components/dist/html-custom-data.json"]
}

Machine API (no install): /custom-elements.json on this docs host. After npm install: @signicat/catnip-components/custom-elements.json.

Next Steps

• Installation — Registry, npm, CDN, one instance (micro-frontends), Vue compiler
• Agent skill — Teach a coding agent how to bind catnip-* tags
• Configuration — CatnipConfig, i18n, window.Catnip
• Components — Explore all components
• Theming — Add dark mode