Skip to main content

Install

Get one component into a project.

This page is for installing a component into your own app. If you're working inside this repository instead, see CONTRIBUTING.md. If you're an agent rather than a person reading this, see Connect for the MCP server, CLI, and text feeds instead.

Install a component

Any project already configured for shadcn, zero extra config:

npx shadcn add https://design.helpmarq.com/r/<name>.json

That drops the source at components/ui/<name>.tsx and installs that component's own npm dependencies (per-component, not registry-wide — most components have none). There's no ns-ui package and nothing to keep in sync afterward. The file is yours; edit it directly.

The same command also writes any custom design token the component needs into your project's CSS file — shadcn's CLI merges the registry entry's cssVars block into your :root/.dark on install (printing "Updating CSS variables" while it does). See Theming for the full token table and what each one controls.

Starting a new project

Initialize shadcn first, then install as above:

npx shadcn init -d
npx shadcn add https://design.helpmarq.com/r/gallery-coverflow-caustic.json

Before you install

Every component is built against, at minimum, five CSS custom properties already in scope on the host app — --background, --foreground, --ns-muted, --border, and --ns-accent — never a hardcoded color, in markup or in canvas/SVG draw code. A component that needs more than that — a card surface, an error or status color — declares it in its own registry entry, and the install command above adds it for you; the full set of ten tokens the registry as a whole draws from is on Theming. A component that draws to a <canvas> reads these with getComputedStyle at mount and again on theme change, rather than baking in a color literal. If your project doesn't define these properties before installing, an installed component won't necessarily error — it may just render with the wrong ink, or invisible ink on one theme. Full detail: Guidelines, "The token rule."

What's assumed about your stack

  • React 19+.
  • Tailwind CSS v4 — every component is styled entirely with Tailwind utility classes: no shipped CSS file, no CSS-in-JS.
  • Geist Sans / Geist Mono, inherited from the host app's own font-family rather than set by the component itself.
  • "use client" is already on every component file, and each ships with zero or minimal npm dependencies of its own.

What the gate guarantees

Every component in the registry passed an automated accessibility audit before merge: every exposed, non-disabled interactive control has an accessible name, a control with role=switch|checkbox|radio carries aria-checked, a visible dialog has an accessible name, and if a component renders any control at all, Tab reaches something. Keyboard focus is also required to render visibly differently from unfocused. What that check does and doesn't cover — presence of a name, not its wording; reachability, not per-element tab order — is on Guidelines.

Motion and performance: convention, not gate

None of the following is checked by the automated gate — it has no prefers-reduced-motion, tab-visibility, or device-pixel-ratio assertion anywhere. These are conventions the codebase holds itself to, at varying degrees of consistency, not guarantees a build enforces:

  • prefers-reduced-motion is close to universal: 288 of 298 components respond to it, either with a matchMedia check that swaps an animation for a static or discrete-step equivalent, or the motion-reduce: Tailwind variant on a CSS transition. It is not universal, and nothing fails a build for the remaining 10.
  • Device-pixel-ratio capping applies only to the canvas-based components (90 of 298 draw to a 2D context) — there is no DPR to cap on anything else. Within that group it's close to universal but not total: 89 of 90 cap the ratio at 2 before sizing their canvas.
  • Pausing on visibilitychange is the weakest of the three: only 63 of 298 components pause their render loop when the tab is hidden, and even scoped to just the canvas-based components it's a minority behavior (48 of 90). Don't assume a given animated component stops rendering in a background tab — check its source.