Skip to content

Installation

Set up your project. Then add components with the shadcn CLI, or copy the files.

Requirements

  • React 19 and TypeScript
  • Tailwind CSS v4
  • A shadcn theme with CSS variables

vip/ui does not support Tailwind CSS v3, JavaScript-only projects, or the shadcn --no-css-variables mode.

Components do not import from next/. You can use them in any React 19 app, such as a Vite app. Blocks install as Next.js App Router routes, so they need Next.js.

Set up your project

If your project does not have a components.json file, run the shadcn init command. For framework steps, see the shadcn installation guide (opens in a new tab).

Make sure that components.json has these values. tailwind.css is the path to your global CSS file.

components.json

Add a theme

Components use the shadcn color tokens, such as --primary and --border. Your shadcn theme works with no changes.

To use the vip/ui colors:

  • Open Themes and select a theme.
  • Copy its CSS into your global CSS file, after the :root and .dark rules.

Each theme sets the color tokens to steps of the color scales. To use the scales in your own styles, such as bg-blue-3, copy their CSS from Colors.

Add a component

Copy the command from a component page, such as Button. Run it from your project root.

The CLI does these steps:

  • Adds the component file to a vip-ui/ folder in your components alias.
  • Adds the files that the component needs, such as utils.ts and popover.tsx. Each file is a separate registry item. All components use the same copy.
  • Installs the packages that the component uses.
  • Adds the Tailwind plugin and theme variables to your global CSS file. It keeps the values that you already set.
  • Does not change the files in your shadcn components/ui/ folder.

Add the namespace

Add vip/ui to the registries in your components.json. Keep your other values.

components.json

Then add items by name. Item names start with vip-.

Install manually

Use these steps if you do not use the CLI.

  1. Install the Tailwind plugin

    The plugin adds Tailwind variants for React Aria states, such as selected: and pressed:.

  2. Add the theme styles

    Add this CSS to your global CSS file one time. It loads the plugin and adds status colors, shadows, and easing curves. All other colors come from your shadcn theme or a vip/ui theme. The radius comes from your shadcn theme.

    globals.css
  3. Install the packages

    Open the Manual tab on the component page. Install the packages that it shows.

  4. Copy the files

    Copy the component file into a vip-ui/ folder in your components folder. Then add the required files that the Manual tab shows. Do not change relative imports, such as ./utils. Examine existing files before you replace them.

Import a component

Import the component from the vip-ui/ folder.

example.tsx

Demo code imports from @/components/vip-ui/. If your alias is different, change the import paths. A demo can use other vip/ui components. Add those components too.

Shared files

Many components use these files. The CLI adds them for you. For a manual installation, add each file one time.

utils.ts

Merges class names with tailwind-variants.

components/vip-ui/utils.ts

motion.ts

Sets the easing curves and springs of animations.

components/vip-ui/motion.ts

size.tsx

Sets one size scale for buttons, toggles, and their groups.

components/vip-ui/size.tsx

button-styles.tsx

Sets the variants and sizes of buttons and button links.

components/vip-ui/button-styles.tsx

field-styles.tsx

Sets the theme styles of text and segmented fields.

components/vip-ui/field-styles.tsx

date-segment.tsx

Shows the editable segments of date and time fields.

components/vip-ui/date-segment.tsx

collapsible-panel.tsx

Animates a disclosure panel and keeps its content accessible.

components/vip-ui/collapsible-panel.tsx

item-highlight.tsx

Moves one highlight to the hovered or focused item.

components/vip-ui/item-highlight.tsx