no-unknown-classes

Catch class names that produce no CSS. This rule checks your installed Tailwind v4 with your theme, custom utilities, variants, and plugins. It suggests spelling corrections when it finds a close match.

Setup

Start with warnings so you can add exceptions for external stylesheets:

"shadcn/no-unknown-classes": "warn"

Keep this rule enabled inside your component directory. It checks plain elements and class helpers as well as recognized components.

Examples

Typos

// Allowed.
<div className="flex-col rounded-lg hover:flex" />

// Reported.
<div className="flex-cols rounded-huge hovr:flex" />

For flex-cols, the error is:

"flex-cols" is not a class this project's Tailwind knows, so no CSS is generated for it. Did you mean "flex-col"?

The correction is also available as an editor suggestion. An unknown variant with no close match gets guidance about @custom-variant.

Classes your theme defines

Custom utilities and plain class selectors in the theme's import graph are recognized:

@utility tap-target {
  min-height: 44px;
}

.legacy-card {
  border: 1px solid var(--border);
}

// Allowed with the stylesheet above.
<div className="tap-target legacy-card" />

Classes generated by a configured Tailwind plugin are also recognized. For example, prose passes when the typography plugin is loaded by your theme.

External stylesheets

Allow classes supplied by CSS outside the theme's import graph:

"shadcn/no-unknown-classes": ["error", {
  allow: ["editor-root", "editor-toolbar"],
}]

// Allowed by the exception.
<div className="editor-root" />

// Reported.
<div className="flex-cols" />

Allow only classes that the application actually loads. An exception does not generate CSS.

Contracts

Limit an external class to the component that uses it:

"shadcn/no-unknown-classes": ["error", {
  componentImports: ["^@/components/editor$"],
  contracts: [
    { pattern: "^Editor$", allow: ["editor-root"] },
  ],
}]

import { Editor } from "@/components/editor"

// Allowed by the contract.
<Editor className="editor-root" />

// Reported: the external class is not allowed on a div.
<div className="editor-root" />

Contracts use resolved component names and also apply through forwarding wrappers. Plain elements and helper calls outside component usage take the top-level policy.

Your own words

"shadcn/no-unknown-classes": ["error", {
  message: 'Unknown class "{{className}}". Check the spelling or use {{suggestions|an existing class}}.',
}]

{{suggestions}} contains the suggested spelling, if available. {{file}} points to the theme CSS. Custom messages keep editor suggestions. See message placeholders.

Interplay with no-raw-colors

Use both rules to cover class names and theme colors:

// no-unknown-classes: a misspelled variant on a valid color.
<div className="hovr:bg-primary" />

// no-raw-colors: a misspelled color token.
<div className="bg-primry" />

A class the grammar reads as a color is left to no-raw-colors when it names a token or misspells one, since that rule can suggest the project's tokens. When Tailwind's nearest real class is not a color, as with text-smal for text-sm, the misspelling is in another utility and this rule reports it.

Options

Option	Default	What it does
allow	Not set	Exempts matching classes from the existence check.
deny	Not set	Removes exemptions. Without allow, exempts every other class.
contracts	[]	Sets exceptions and messages for matching components.
message	Built-in guidance	Replaces error text. Editor suggestions remain available.

The rule also accepts recognition options. Entries support class matching, but are not validated against the grammar because they may name external classes.

deny only removes an exception; it does not make a valid class invalid. Using deny alone lets other unknown classes pass, including typos.

Without a resolvable theme

If Tailwind or the theme cannot load, the rule uses the bundled class grammar, discovered @utility names, and CSS class selectors. A failed theme build produces a warning. Other projects in the same run continue using their own themes.

This fallback checks less: it accepts arbitrary variant prefixes and some invented values, and provides no spelling suggestions. For example, hovr:flex may pass. Fix the theme-loading warning before relying on a clean result. See caching.

Limits

• A known class can still be used in the wrong place. Use no-restyle for component rules.
• Markers, arbitrary properties, and known CSS class selectors bypass the Tailwind query. This rule does not validate their CSS behavior.
• allow: ["layout"] can exempt hovr:flex because matching uses the base class. Allow external classes by name rather than broad category.
• Unclassified names such as flex-cols are not layout. On a component, both this rule and no-restyle may report them.
• Unreadable class values need require-static-classes.

See analysis limits for shared limits.