Installation
Install SevenUI primitives with the shadcn CLI. The @sevenui registry is in the shadcn registry index, so any primitive installs by name.
SevenUI requires a project already set up with the shadcn CLI and Tailwind CSS v4. If you have not initialized one yet, pick the Base UI base, since every SevenUI primitive is built on it:
init can write starter primitives of its own, such as
components/ui/button.tsx. The first time you add SevenUI primitives
over those files, pass --overwrite:
Without it the CLI asks before replacing each existing file. In a
non-interactive shell (CI, an AI agent) there is no one to answer, and
the command exits with “Done” having written none of the requested
files. Leave --overwrite off later on, once you have edited primitives
you want to keep.
Add primitives
@sevenui is listed in the
shadcn registry index,
so the CLI resolves the namespace with no extra configuration:
Bash
Primitives install as source files under your ui alias.
Animations
Overlay primitives (dialog, menus, popover, select, …) animate through
SevenUI’s own enter/exit utilities (animate-in, fade-in-0,
zoom-in-95, slide-in-from-*, …) — no animation package is involved.
The @utility and @keyframes definitions live in a single
animations registry item that every animated primitive depends on, so
the shadcn CLI merges them into your stylesheet automatically. Speed and
easing compose with Tailwind core’s duration-* / ease-* utilities.
If you copy primitive source manually instead of using the CLI, copy the
css block from https://sevenui.dev/r/animations.json into your
global stylesheet too — the accordion additionally ships its own
accordion-down / accordion-up keyframes in its item the same way.
Registry layout
The registry is namespaced by kind, one namespace per tier: primitives at
/r/<name>.json, components — the composed examples on
sevenui.dev/components — at
/r/component/<name>.json, docs demos at /r/demo/<name>.json, and pro
blocks at /r/pro/<name>.json.
A component installs the same way as a primitive:
Bash
The @sevenui namespace form works the same way:
The file lands in your components/ directory as a single self-contained
component, and the primitives it depends on (accordion itself, in this case)
land in components/ui/.
Browse components at sevenui.dev/components and pro blocks at sevenui.dev/blocks.
Pro blocks
Blocks install through the same @sevenui registry as everything else,
with your Pro license key sent along. Copy the key from
your account, then:
Put the key in your environment. In a Next.js project .env.local is
the natural place; .env works too, and the shadcn CLI reads both. Keep
the file out of version control.
Give the @sevenui registry an Authorization header in
components.json, once:
Then add any block by name:
The header applies to the whole @sevenui namespace, not only to
blocks. Once it is in components.json, the CLI requires
SEVENUI_PRO_KEY for every @sevenui install, free primitives and
components included. Where the variable is unset, every install stops
with:
Set it everywhere shadcn add runs: each teammate’s machine and CI.
A 401 means no key reached the registry; a 403 means the key was
rejected. The support FAQ covers both.
Troubleshooting
Text renders in a serif font
shadcn init can write --font-sans: var(--font-sans); into the
@theme inline block of globals.css. The variable refers to itself,
so it resolves to nothing and the page falls back to the browser’s
default serif. A create-next-app layout defines its font as
--font-geist-sans; point the theme at that instead:
toast.add() shows nothing
Toasts render through <Toaster />, which has to be mounted once. See
Toast setup.