Tailwind CSS Components

1. Component Class Patterns

Standard Tailwind class recipes for common UI components. Use these as the baseline and extend as needed.

1.1 Buttons

1.2 Form Controls

1.3 Display Components

1.4 Table

1.5 Tabs

1.6 Dropdown / Popover

1.7 Modal / Dialog

2. HeadlessUI Integration

2.1 Component Import Map

2.2 Data Attribute Styling

HeadlessUI exposes component state via data attributes. Use these instead of managing state classes manually.

2.3 Dialog Pattern

<Dialog open={isOpen} onClose={setIsOpen} className="relative z-50">
  <DialogBackdrop className="fixed inset-0 bg-black/30 duration-300 ease-out data-[closed]:opacity-0" />
  <div className="fixed inset-0 flex w-screen items-center justify-center p-4">
    <DialogPanel className="max-w-lg rounded-xl bg-white p-6 shadow-xl duration-300 ease-out data-[closed]:scale-95 data-[closed]:opacity-0">
      <DialogTitle className="text-lg font-semibold">Title</DialogTitle>
      <p className="mt-2 text-sm text-gray-500">Description text.</p>
      <div className="mt-4 flex justify-end gap-3">
        <button onClick={() => setIsOpen(false)} className="rounded-md bg-white px-3 py-2 text-sm font-semibold text-gray-900 ring-1 ring-inset ring-gray-300 hover:bg-gray-50">Cancel</button>
        <button onClick={handleConfirm} className="rounded-md bg-indigo-600 px-3 py-2 text-sm font-semibold text-white shadow-sm hover:bg-indigo-500">Confirm</button>
      </div>
    </DialogPanel>
  </div>
</Dialog>

2.4 Switch Pattern

<Switch
  checked={enabled}
  onChange={setEnabled}
  className="group relative inline-flex h-6 w-11 shrink-0 cursor-pointer rounded-full border-2 border-transparent bg-gray-200 transition-colors duration-200 ease-in-out focus:outline-none focus:ring-2 focus:ring-indigo-600 focus:ring-offset-2 data-[checked]:bg-indigo-600"
>
  <span className="pointer-events-none inline-block size-5 transform rounded-full bg-white shadow ring-0 transition duration-200 ease-in-out group-data-[checked]:translate-x-5" />
</Switch>

2.5 Menu Pattern

<Menu>
  <MenuButton className="inline-flex items-center gap-x-1.5 rounded-md bg-white px-3 py-2 text-sm font-semibold text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300 hover:bg-gray-50">
    Options
    <ChevronDownIcon className="-mr-1 size-5 text-gray-400" />
  </MenuButton>
  <MenuItems className="absolute right-0 z-10 mt-2 w-56 origin-top-right rounded-md bg-white shadow-lg ring-1 ring-black/5 transition duration-100 ease-out data-[closed]:scale-95 data-[closed]:opacity-0 focus:outline-none">
    <MenuItem>
      <a href="#" className="block px-4 py-2 text-sm text-gray-700 data-[focus]:bg-gray-100">Edit</a>
    </MenuItem>
    <MenuItem>
      <a href="#" className="block px-4 py-2 text-sm text-gray-700 data-[focus]:bg-gray-100">Delete</a>
    </MenuItem>
  </MenuItems>
</Menu>

2.6 Listbox (Select) Pattern

<Listbox value={selected} onChange={setSelected}>
  <ListboxButton className="relative w-full cursor-default rounded-md bg-white py-1.5 pl-3 pr-10 text-left text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300 focus:outline-none focus:ring-2 focus:ring-indigo-600 sm:text-sm/6">
    {selected.name}
    <ChevronUpDownIcon className="pointer-events-none absolute inset-y-0 right-0 flex items-center pr-2 size-5 text-gray-400" />
  </ListboxButton>
  <ListboxOptions className="absolute z-10 mt-1 max-h-60 w-full overflow-auto rounded-md bg-white py-1 text-base shadow-lg ring-1 ring-black/5 focus:outline-none sm:text-sm">
    {options.map((option) => (
      <ListboxOption key={option.id} value={option} className="relative cursor-default select-none py-2 pl-3 pr-9 text-gray-900 data-[focus]:bg-indigo-600 data-[focus]:text-white">
        {option.name}
      </ListboxOption>
    ))}
  </ListboxOptions>
</Listbox>

3. Component Composition

3.1 Sub-Component Pattern

Structure complex components with semantic sub-components for clear slot-based composition.

3.2 Polymorphic Components with as

HeadlessUI components accept an as prop to change the rendered element.

3.3 Slot Pattern with data-slot

Use data-slot attributes to style child components from a parent context.

function Card({ children }) {
  return <div className="rounded-lg bg-white shadow [&_[data-slot=header]]:border-b [&_[data-slot=header]]:px-6 [&_[data-slot=header]]:py-4 [&_[data-slot=body]]:px-6 [&_[data-slot=body]]:py-4">
    {children}
  </div>
}

function CardHeader({ children }) {
  return <div data-slot="header">{children}</div>
}

3.4 Group-Based Styling

Use the group class on a parent to style children based on parent state.

3.5 ForwardRef for Reusable Components

Always use forwardRef when building reusable components that wrap native elements or HeadlessUI components. This ensures compatibility with HeadlessUI's internal ref management and allows parent components to access the DOM node.

const Button = forwardRef(function Button({ className, variant = 'primary', ...props }, ref) {
  return <button ref={ref} className={clsx(buttonVariants[variant], className)} {...props} />
})

4. className Helpers

4.1 Utility Comparison

4.2 Combined Helper

import { clsx } from 'clsx'
import { twMerge } from 'tailwind-merge'

function cn(...inputs) {
  return twMerge(clsx(inputs))
}

4.3 Usage Rules

5. Transition and Animation

5.1 HeadlessUI Transition Data Attributes

HeadlessUI components support built-in transitions via data attributes. No <Transition> wrapper needed.

5.2 Common Transition Recipes

5.3 Asymmetric Timing

Use different durations for enter and leave to make exits feel snappier.

className="transition data-[enter]:duration-300 data-[enter]:ease-out data-[leave]:duration-200 data-[leave]:ease-in data-[closed]:opacity-0"

5.4 Reduced Motion

Always gate non-essential animations behind motion-safe: or disable with motion-reduce:.

6. Form Components

6.1 Input with Label and Help Text

<div>
  <label htmlFor="email" className="block text-sm/6 font-medium text-gray-900">Email</label>
  <div className="mt-2">
    <input type="email" id="email" name="email" className="block w-full rounded-md bg-white px-3 py-1.5 text-base text-gray-900 outline outline-1 -outline-offset-1 outline-gray-300 placeholder:text-gray-400 focus:outline-2 focus:-outline-offset-2 focus:outline-indigo-600 sm:text-sm/6" />
  </div>
  <p className="mt-2 text-sm text-gray-500">We will never share your email.</p>
</div>

6.2 Fieldset with Legend

<fieldset>
  <legend className="text-sm/6 font-semibold text-gray-900">Notifications</legend>
  <p className="mt-1 text-sm text-gray-500">How should we contact you?</p>
  <div className="mt-4 space-y-4">
    {/* Radio/checkbox items here */}
  </div>
</fieldset>

6.3 Checkbox with Grid Overlay

<div className="relative flex items-start">
  <div className="flex h-6 items-center">
    <input id="terms" name="terms" type="checkbox" className="size-4 rounded border-gray-300 text-indigo-600 focus:ring-indigo-600" />
  </div>
  <div className="ml-3 text-sm/6">
    <label htmlFor="terms" className="font-medium text-gray-900">Accept terms</label>
    <p className="text-gray-500">You agree to our terms of service and privacy policy.</p>
  </div>
</div>

6.4 Validation States

Add aria-invalid="true" and aria-describedby="field-error" on error inputs. Place error message in an element with matching id.

7. Interactive Feedback

7.1 Toast / Notification

Use aria-live="polite" on the toast container for screen reader announcement.

7.2 Alert with Dismiss

<div className="rounded-md bg-yellow-50 p-4">
  <div className="flex">
    <ExclamationTriangleIcon className="size-5 text-yellow-400" />
    <div className="ml-3">
      <h3 className="text-sm font-medium text-yellow-800">Attention needed</h3>
      <p className="mt-2 text-sm text-yellow-700">Your trial expires in 3 days.</p>
    </div>
    <div className="ml-auto pl-3">
      <button type="button" className="-m-1.5 inline-flex rounded-md p-1.5 text-yellow-500 hover:bg-yellow-100 focus:outline-none focus:ring-2 focus:ring-yellow-600 focus:ring-offset-2 focus:ring-offset-yellow-50">
        <span className="sr-only">Dismiss</span>
        <XMarkIcon className="size-5" />
      </button>
    </div>
  </div>
</div>

7.3 Empty State

7.4 Loading States

7.5 Progress

Add role="progressbar" with aria-valuenow, aria-valuemin="0", aria-valuemax="100", and aria-label.

8. Accessibility Per Component

8.1 ARIA Requirements

8.2 Focus Visibility

Always ensure focus indicators are visible. Tailwind default: focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-600. Never use outline-none without a replacement indicator like a ring: focus-visible:ring-2 focus-visible:ring-indigo-600.

8.3 Screen Reader Utilities

9. Common Mistakes

MCP Component Library

The frontend-components MCP server provides ready-made component examples:

• HyperUI (hyperui): 481 HTML/Tailwind components — badges, modals, tables, forms, dropdowns, tabs, and more
• HeadlessUI React (headlessui-react): 38 accessible component examples — Dialog, Menu, Listbox, Combobox, Switch, Tabs
• HeadlessUI Vue (headlessui-vue): 30 accessible Vue component examples
• DaisyUI (daisyui): 65 component class references — semantic classes like btn, card, modal with all modifiers
• FlyonUI (flyonui): 49 CSS components + 24 JS plugins for interactive components

Quick lookup: search_components(query: "modal") or get_component(framework: "hyperui", category: "application", component_type: "modals", variant: "1")