responsive-tailwind

Type-safe responsive Tailwind CSS class composition with compile-time breakpoint validation and arbitrary breakpoint support.

responsive-tailwind is a small utility for composing responsive Tailwind CSS classes using an object-based syntax with full TypeScript validation.

It helps organize responsive classes while ensuring every breakpoint value uses the correct Tailwind prefix, preserving Tailwind's static class detection.

Features

• ✅ Object-based responsive class composition
• ✅ Compile-time validation of breakpoint prefixes
• ✅ Supports Tailwind default breakpoints
• ✅ Supports arbitrary breakpoints (min-[...] / max-[...])
• ✅ Works with Tailwind JIT/static class detection
• ✅ Uses tailwind-merge for intelligent class merging
• ✅ Full TypeScript support

---

Installation

npm install responsive-tailwind

or:

yarn add responsive-tailwind

or:

pnpm add responsive-tailwind

---

Usage

import { responsive } from "responsive-tailwind";

const className = responsive({
  base: "flex flex-col gap-4",
  md: "md:flex-row",
  lg: "lg:gap-8",
});

// Result:
// "flex flex-col gap-4 md:flex-row lg:gap-8"

Use the breakpoint key to organize your classes, and include the full Tailwind prefix in the value.

---

React Example

Use responsive directly inside the className prop:

import { responsive } from "responsive-tailwind";

export function Card() {
  return (
    <div
      className={responsive({
        base: "flex flex-col gap-4 p-4",
        md: "md:flex-row",
        lg: "lg:p-8",
      })}
    >
      <div className="flex-1">
        Content
      </div>

      <div className="flex-1">
        Sidebar
      </div>
    </div>
  );
}

The generated class string will be:

flex flex-col gap-4 p-4 md:flex-row lg:p-8

This allows you to keep responsive styles organized while still using Tailwind classes normally.

---

Why include the prefix?

responsive-tailwind intentionally does not generate breakpoint prefixes automatically.

Instead of:

responsive({
  md: "flex-row"
});

you write:

responsive({
  md: "md:flex-row"
});

This keeps classes visible to Tailwind's static analyzer and prevents issues with dynamic class generation.

---

TypeScript validation

Invalid breakpoint prefixes are detected during development.

Valid

responsive({
  sm: "sm:flex-col",
  md: "md:flex-row",
  lg: "lg:grid-cols-3",
});

Invalid

responsive({
  md: "flex-row",
});

TypeScript error:

Class 'flex-row' in md must start with 'md:'

---

Custom breakpoints

You can use Tailwind arbitrary breakpoints:

responsive({
  base: "grid",
  "min-[900px]": "min-[900px]:grid-cols-3",
  "max-[500px]": "max-[500px]:hidden",
});

Examples:

responsive({
  "min-[768px]": "min-[768px]:flex-row",
  "max-[1024px]": "max-[1024px]:grid-cols-1",
});

---

Supported breakpoints

Default Tailwind breakpoints:

responsive({
  sm: "sm:...",
  md: "md:...",
  lg: "lg:...",
  xl: "xl:...",
  "2xl": "2xl:...",
});

Arbitrary breakpoints:

responsive({
  "min-[value]": "min-[value]:...",
  "max-[value]": "max-[value]:...",
});

---

API

responsive(classes)

Receives a responsive class map and returns a merged Tailwind class string.

Example:

responsive({
  base: "flex items-center",
  md: "md:flex-row",
  "min-[1200px]": "min-[1200px]:gap-8",
});

Output:

flex items-center md:flex-row min-[1200px]:gap-8

---

How it works

The library:

1. Receives classes grouped by breakpoint.
2. Validates that each breakpoint value contains its matching Tailwind prefix.
3. Merges all classes using tailwind-merge.
4. Returns a single className string.

---

License

MIT