eslint-plugin-tailwind-classname-order

This eslint plugin automatically orders the tailwind classes included in the className tags from each element by the provided default order list.

• 1. Features
• 2. Roadmap
• 3. Currently supported tailwind classes
• 4. Explicitly unsupported classes
• 5. Default order config
• 6. Installation
• 7. Usage

Features

• [x] Order tailwind classes by given config
• [x] Recognize predefined classes
• [x] Recognize negative valued class names
• [x] Recognize states like hover,active,peer etc.
• [x] Recognize stacked states properly.
• [x] Recognize mediaquerys
• [x] Support for tailwind-rn
• [x] Supporting not only strings, but also expressions

Development

Requires Node.js 20.19 or newer and Yarn 1.x.

yarn install
yarn verify

cd playground
yarn install
cd ..
yarn verify:all

Roadmap

1. Resolve custom background images from project theme data when Tailwind offers a stable synchronous API.
2. ~~Include className objects that are not string typed instead of just ignoring them.~~
3. ~~Make custom ordering for the user more accessible and easier.~~

Currently supported tailwind classes

For the latest version the following tailwind classes are supported by the order plugin. Classes that are not yet included, will be treated as predefined custom classes. Classes are categorized as seen in the tailwind documentation here

Custom background images defined in a Tailwind theme must include img in their class name so the plugin can distinguish them from custom colors:

bg-home-img
bg-img-hero

Without theme evaluation, an ambiguous name such as bg-hero could represent either background-image or background-color and is therefore treated as a color. Built-in gradients and arbitrary image values such as bg-[url('/hero.jpg')] are detected automatically. Arbitrary colors such as bg-[#fff] and bg-[color:var(--brand)] retain background-color priority.

Explicitly unsupported classes

Some classes in tailwind have counterparts with the same name and since interpreting arbitrary values is not supported on the current version, they won't be detected properly. There are two major differences:

1. The plugin doesn't support arbitrary values in any way for the certain class. Even when they're predefined in the tw config file, they won't be interpreted properly.
2. The plugin can't interpret arbitrary values when they're added inline, but the plugin will be able to detect the proper class, when the value is predefined in the config. This Problem will presumably be fixed with a future version.

• Font Family (inline)
• Text Color (inline)
• Text Decoration Color (inline)
• Background Size (arbitrary generally)
• Background Position (arbitrary generally)
• Stroke Color (inline)
• Border Color (inline)
• Outline Color (inline)
• Ring Color (inline)
• Ring Offset Color (inline)
• Box Shadow Color (inline)

Default order config

• predefined class

#browser behavior

• box-sizing

#object reference - High priority because it refers to neighboring content

• peer
• group

#object identity, positioning (where)

• position
• (position) top, right, bottom, left
• visibility
• z-index

#object identity, sizing (how)

• (flex) flex width
• (flex) basis
• container
• width
• width-min
• width-max
• height
• height-min
• height-max
• aspect-ratio

#object identity, core identity (what)

• display

#flex identity, core flex identity (what flex)

• (flex) direction (row/col)
• (flex) wrap

#grid identity, core grid identity (what grid)

• (grid) grid-cols (grid-template-columns)
• (grid) grid-column
• (grid) grid-rows (grid-template-rows)
• (grid) grid-row
• (grid) grid-flow
• (grid) auto-cols
• (grid) auto-rows
• (grid) justify items
• (grid) justify self
• (grid) align content

#flex/grid identity, core flex/grid identity (what flex/grid)

• (flex / grid) justify-content
• (flex / grid) align-items
• (flex / grid) align self
• (flex / grid) gap (x, y)

#object identity, environmental behaviour

• place items
• place content
• place self
• padding-x
• padding-y
• padding (top, right, bottom, left)
• margin-x
• margin-y
• margin (top, right, bottom, left)
• space between (x, y)
• float
• clear
• isolation

#object identity modification

• transform (x, y, rotate, scale, skew)
• transform origin

#content behaviour

• object fit
• object position
• overflow
• overscroll
• order
• break-before
• break-after
• break-inside
• box decoration break

#styling - content / text related

• whitespace

#text styling

• font-family
• font-size
• font smoothing
• font-weight
• font-style
• font-variant-numeric
• tracking (letter spacing)
• leading (line-height)
• list style type
• list style position
• text alignment
• text-color
• text-transform
• text-overflow
• text-decoration
• text-decoration-color
• text-decoration-style
• text-decoration-thickness
• text-underline-offset
• text-indent
• word break
• vertical align
• pseudo-class content

#body behaviour

• opacity

#body styling

• background (url, repeat, pos, size)
• background-attachment
• background-clip
• background-color
• background-origin
• gradient color from-{color}
• gradient color middle-{color}
• gradient color to-{color}
• mix-blend-mode
• background blend mode
• (svg) fill
• (svg) stroke color
• (svg) stroke width
• border (style, width, radius)
• border-color
• divide (x, y)
• divide color
• divide-style
• outline-width
• outline-style
• outline-offset
• ring width
• ring color
• ring offset width
• ring offset color
• box-shadow
• box-shadow-color

#table styling

• border-collapse
• border-spacing
• table-layout

#filters

• blur
• brightness
• contrast
• drop-shadow
• grayscale
• hue-rotate
• invert
• saturate
• sepia
• backdrop blur
• backdrop brightness
• backdrop contrast
• backdrop grayscale
• backdrop hue rotate
• backdrop invert
• backdrop opacity
• backdrop saturate
• backdrop sepia

#transitions & animation

• transition (property, duration, timing function, delay)
• animate

#interactivity

• accent-color
• appearance
• cursor
• caret-color
• pointer events
• resize
• scroll behavior
• scroll padding (x, y)
• scroll margin (x, y)
• scroll snap align
• scroll snap stop
• scroll snap type
• touch action
• user select
• will-change

#accesiblility

• screen readers

#state management

States are priority wise in the same order as they are presented on the tailwind docs (states), excluding the @media type prefixes.

#media queries

This plugin supports the default breakpoint prefixes as listed on the tailwind docs for responsive design. Furthermore more custom prefixes are also already added. The orderConfig.json file can of course be altered to include even more custom breakpoint prefixes.

• xs
• sm
• md
• 2md
• lg
• 2lg
• xl
• 2xl
• 3xl

Installation

You'll first need to install ESLint:

With npm

# via npm
npm install eslint --save-dev

# via yarn
yarn add -D eslint

Next, install eslint-plugin-tailwind-classname-order:

# via npm
npm install @aacn.eu/eslint-plugin-tailwind-classname-order --save-dev

# via yarn
yarn add -D @aacn.eu/eslint-plugin-tailwind-classname-order

Usage

Use the recommended flat config in eslint.config.mjs:

import tailwindClassnameOrder from '@aacn.eu/eslint-plugin-tailwind-classname-order';

export default [...tailwindClassnameOrder.configs.recommended];

By default the rule sorts className. Configure other JSX attributes when needed:

export default [
  ...tailwindClassnameOrder.configs.recommended,
  {
    rules: {
      '@aacn.eu/tailwind-classname-order/order': [
        'warn',
        { attributes: ['className', 'class'] },
      ],
    },
  },
];

Custom class order

Generate a project config in the current directory:

npx tw-class-order
# or
yarn exec tw-class-order

This creates a small tw-class-order.json without copying and freezing the bundled defaults:

{
  "before": {
    "project-card": "block"
  },
  "after": {
    "project-shadow": "shadow"
  }
}

Each key is a custom class group and each value is an existing anchor in the default order. The example places project-card before the display block group and project-shadow after the shadow group. The command refuses to overwrite an existing file.

When ESLint runs, the plugin searches from the current directory toward the filesystem root and uses the nearest config. If none exists, the bundled order is used unchanged. Invalid JSON, invalid mappings, and missing anchors produce an error instead of silently using a surprising order.

A complete { "priority": [...] } config is still supported when replacing the entire bundled order is intentional, but overrides continue receiving new built-in Tailwind groups when the package is upgraded.

When the rule reports an ordering problem, the diagnostic includes the expected class sequence; ESLint autofix applies the same sequence.