How to have the shadcn registry distribute custom css

[FifthWit]

Hi, so I am working on a ui library that is distributed via the cli/registry system, and I need to add some custom tailwind classes that can't be added via regular classes, so I gotta edit the css manually, but I don't see any docs nor posts on how to distribute custom css, besides adding css variables. Is there a way to do that, or should I tell the users to copy paste the css manually?

[BitWise-0x]

The registry system actually does support distributing custom CSS — it's just not well documented. The field you want is css in your registry item JSON.

The css field

When the CLI installs a registry item with a css field, it uses PostCSS to merge the CSS into the project's existing Tailwind CSS file. It's idempotent, so running install twice won't duplicate rules.

Here's how to use it for different scenarios:

Custom @utility directives

{
  "name": "my-component",
  "type": "registry:ui",
  "css": {
    "@utility content-auto": {
      "content-visibility": "auto"
    },
    "@utility tab-*": {
      "tab-size": "var(--tab-size-*)"
    }
  }
}

Layer-scoped CSS (@layer base, @layer components)

{
  "css": {
    "@layer base": {
      "h1": { "font-size": "var(--text-2xl)" }
    },
    "@layer components": {
      ".card-fancy": { "background": "linear-gradient(...)" }
    }
  }
}

Keyframe animations

These get placed under @theme inline automatically:

{
  "css": {
    "@keyframes slide-in": {
      "from": { "transform": "translateX(-100%)" },
      "to": { "transform": "translateX(0)" }
    }
  }
}

Tailwind plugins

Make sure to also list the plugin in dependencies:

{
  "css": {
    "@plugin \"@tailwindcss/typography\"": {}
  },
  "dependencies": ["@tailwindcss/typography"]
}

Regular CSS with @apply

@apply directives are keys with empty object values — the CLI merges duplicate @apply rules using twMerge:

{
  "css": {
    ".my-custom-class": {
      "display": "flex",
      "@apply items-center gap-2": {}
    }
  }
}

CSS imports

These get placed at the top of the file:

{
  "css": {
    "@import \"some-package/styles.css\"": {}
  }
}

How the merging works under the hood

The CLI parses the project's existing CSS file with PostCSS, then for each entry in your css object:

• Finds or creates the matching at-rule/selector
• Replaces existing declarations with the same property, appends new ones
• Imports go to the top, plugins after imports, keyframes under @theme inline

So no, you definitely don't need users to copy-paste CSS manually. The css field handles it cleanly.

[Pleo2]

This is now an officially documented registry feature: put the CSS in the registry item css field and the CLI applies it to the Tailwind CSS file configured by the consumer project.

A minimal v4 item can be:

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "fancy-card",
  "type": "registry:component",
  "css": {
    "@layer components": {
      ".fancy-card": {
        "background-color": "var(--color-card)",
        "box-shadow": "var(--shadow-lg)"
      }
    },
    "@utility content-auto": {
      "content-visibility": "auto"
    }
  }
}

The same field supports @layer base, @layer components, @utility, @keyframes, @plugin, and @import. If a plugin comes from npm, also declare its package in dependencies.

Use cssVars for tokens and css for selectors, declarations, utilities, keyframes, imports, and plugins. A registry:file is only necessary when the consumer truly needs a separate physical stylesheet rather than rules merged into its configured stylesheet.

Official schema and examples:

• https://ui.shadcn.com/docs/registry/registry-item-json#css
• https://ui.shadcn.com/docs/registry/examples#add-custom-css