Filters

Purpose and Scope

Filter utilities apply CSS image-processing functions to an element itself. In Tailwind CSS, this family covers effects such as blur, brightness, contrast, drop shadow, grayscale, hue rotation, inversion, saturation, and sepia tone. These utilities are useful when an image, icon, card, or rendered component should be visually adjusted without authoring a separate stylesheet rule. The official documentation presents saturation and sepia as representative pages in this family: saturation utilities emit a saturation filter, while sepia utilities emit a sepia filter. The same usage pattern carries across the rest of the filter family.

The reader problem for this page is twofold. First, you need a practical reference for choosing the correct class shape, including numeric values, arbitrary values, custom properties, responsive prefixes, and state variants. Second, you need to know which Tailwind runtime actually sees those classes and turns them into CSS. A class in a template is not magic by itself; it becomes CSS when the core compiler receives the candidate through the browser runtime, the command-line interface, a Node integration, or another build-tool package. Sources: packages/tailwindcss/src/index.ts, packages/tailwindcss/package.json

Filters should be distinguished from backdrop filters. A normal filter changes the pixels of the element it is applied to, so a filtered image, SVG, or card content is rendered differently. A backdrop filter changes the pixels behind a translucent element, so the visible background through that element is adjusted instead. The official documentation mirrors this distinction with separate class prefixes: a saturation utility affects the element, while a backdrop saturation utility affects the backdrop. Keep that distinction in mind before reaching for custom CSS, because many visual effects are already covered by first-party class families.

Relevant Source Files

• packages/tailwindcss/src/index.ts - Defines the core compiler-facing module, compile options, feature flags, theme parsing, import handling, utility creation imports, variant substitution imports, and candidate compilation imports used by integrations.
• packages/tailwindcss/package.json - Declares the tailwindcss package metadata, published CSS entry points, TypeScript entry point, compatibility exports, package files, and core package build scripts.
• package.json - Defines the root monorepo scripts for formatting, linting, building, unit tests, integration tests, UI tests, benches, and playground development.
• packages/@tailwindcss-browser/src/index.ts - Implements the browser runtime that creates a Tailwind compiler, reads browser style tags, injects the main import when needed, maps virtual CSS assets, and builds CSS for classes found on the page.
• packages/@tailwindcss-cli/src/index.ts - Implements the command-line entry point, build command routing, help output, root option parsing, and the canonicalize command for candidate lists.
• packages/@tailwindcss-node/src/index.ts - Re-exports Node-facing compile, optimization, source-map, path normalization, environment, and instrumentation APIs, and installs an ESM cache resolver hook when supported.

These files matter because filter utilities are ordinary Tailwind utilities rather than a separate rendering subsystem. The package metadata exposes the framework and its CSS layers; the core source entry point defines how CSS is parsed, how candidates are compiled, and how feature flags describe the compilation result; the runtime packages provide different ways to feed class candidates into the compiler. When you write a saturation or sepia class in markup, the class follows the same candidate path as spacing, layout, typography, and color utilities. Sources: packages/tailwindcss/src/index.ts, packages/@tailwindcss-browser/src/index.ts, packages/@tailwindcss-cli/src/index.ts, packages/@tailwindcss-node/src/index.ts

Utility Syntax Reference

Use filter utilities when the visual treatment is part of the element’s rendered appearance. The official saturation page defines numeric saturation classes as percentage-based filters, custom-property forms as variable-backed filters, and arbitrary-value forms as direct CSS values. The official sepia page follows the same structure, with a full-effect class plus numeric, custom-property, and arbitrary-value forms. This makes the family predictable: start with the documented scale when it communicates the design, use a bracketed value when the exact CSS function argument matters, and use the parenthesized custom-property form when the value belongs to a design token or runtime variable.

A class such as a saturation or sepia utility is best understood as a candidate. A candidate is a class-like token that Tailwind can parse, validate, combine with variants, and emit only when it is used. The core source imports candidate compilation, utility creation, design-system construction, variant substitution, CSS function substitution, theme handling, and import handling. That source shape explains why filters compose with the rest of the framework: the filter class is not generated by a special image pipeline, it is generated by the same compiler that handles the utility layer as a whole. Sources: packages/tailwindcss/src/index.ts

Variants, Custom Values, and Composition

Filter utilities are commonly combined with responsive and state variants because visual effects often change with context. The official saturation documentation shows a medium-breakpoint saturation utility, and the official sepia documentation shows applying sepia by default and removing it at a breakpoint. This pattern is useful for art direction: mobile layouts can use a muted treatment while larger layouts reveal richer media, or a card can begin grayscale and become full color on hover. The utility determines the CSS declaration, while the variant determines when the selector or media condition applies.

<img
  class='grayscale hover:grayscale-0 brightness-90 md:saturate-150 transition'
  src='/img/mountains.jpg'
  alt='Mountain landscape'
/>

Custom values are appropriate when the design is precise or externally controlled. For example, a bracketed saturation amount communicates a one-off CSS value, while a custom-property form communicates that the value is defined elsewhere. The official docs describe the parenthesized custom-property form as shorthand for an arbitrary value that wraps the property in a variable function automatically. That distinction is helpful in component libraries: a theme variable can tune a whole card family, while an arbitrary value can handle a single campaign image or illustration without expanding the design token surface.

<style type='text/tailwindcss'>
  @theme {
    --hero-saturation: 140%;
    --hero-sepia: 35%;
  }
</style>
 
<img class='saturate-(--hero-saturation) sepia-(--hero-sepia) md:sepia-0' src='/img/mountains.jpg' alt='' />

System-to-Code Mapping

The published core package is the authoritative package for Tailwind CSS. Its package metadata describes Tailwind as a utility-first CSS framework and exports the main package entry, public CSS files, compatibility helpers, plugin entry points, default theme access, color access, and utility CSS files. For filter utilities, the relevant public layer is the utilities layer because the final generated CSS is utility CSS. The same package also exposes the TypeScript source entry during development and built library entries through publish configuration, which is how integrations can depend on a stable package surface. Sources: packages/tailwindcss/package.json

The core TypeScript entry point shows the compiler-facing contract behind those package exports. It defines a configuration type, a compile-options shape with base path, source path, polyfill controls, module loading, and stylesheet loading, plus feature flags for import usage, utilities, variants, theme functions, plugin compatibility, and theme blocks. Those names matter for filters because they show what the compiler is tracking around a filter class: not a filter-specific mode, but a complete stylesheet compilation context that includes imports, themes, variants, custom utilities, and source-map-aware AST output. Sources: packages/tailwindcss/src/index.ts

The root workspace package explains how maintainers and contributors validate changes across the monorepo. Formatting and linting are separate from builds; builds are coordinated through Turbo; tests combine Rust tests and Vitest; integration tests run from the integrations workspace; UI tests include the core package and browser package. If a filter-related regression is suspected, that script layout suggests multiple validation levels. A syntax or compiler issue belongs in the normal test path, a build-tool interaction belongs in integration tests, and a browser runtime issue can be exercised through the browser UI test path. Sources: package.json

Execution Flow Across Runtimes

In browser or Play CDN-style workflows, Tailwind compiles in the page. The browser runtime reads style tags whose type is the Tailwind input CSS type, observes those stylesheets, concatenates their content, and injects the main framework import when no explicit import is present. It then creates a compiler with a browser base path and custom stylesheet and module loaders. The runtime keeps a set of already-seen classes so it can pass only new classes to later builds. That means a newly added filter class in the DOM is treated as another candidate for incremental browser compilation. Sources: packages/@tailwindcss-browser/src/index.ts

The browser runtime also maps supported framework imports to bundled virtual assets. Imports for the main framework, preflight, theme, and utilities resolve to in-package browser assets; unsupported imports throw an error. This matters for filter experimentation because a small browser demo can either rely on automatic framework import injection or explicitly import the utilities layer, but it cannot import arbitrary local stylesheets through the browser runtime. If a filter utility does not appear in a browser demo, confirm that the style tag is using the correct input type and that the class exists in the page after the runtime has initialized. Sources: packages/@tailwindcss-browser/src/index.ts

In command-line workflows, the CLI provides a direct build surface. Its entry point parses process arguments, supports a root build mode, supports an explicit build subcommand, displays help when requested, and delegates actual CSS generation to the build command module. It also exposes a canonicalize command for candidate lists. For filter work, the command-line path is useful when you want a repeatable local build that sees project files and emits output CSS, rather than a browser-only demonstration. The class syntax remains the same, but the surrounding source discovery and output handling are driven by command options. Sources: packages/@tailwindcss-cli/src/index.ts

In Node-integrated workflows, the Node package is the lower-level runtime surface. It re-exports compile, optimization, source-map, normalization, instrumentation, and environment helpers, then installs an ESM cache resolver hook when the Node runtime supports it. The Bun branch avoids that hook because Bun already populates the relevant cache. For filters, this means build-tool integrations can compile and optimize CSS while preserving path and source-map behavior without reimplementing Tailwind’s compiler entry points. A filter class encountered by a Vite, PostCSS, or framework integration still ultimately depends on the same candidate compilation model. Sources: packages/@tailwindcss-node/src/index.ts

Practical Guidance and Edge Cases

Choose numeric utilities when the effect is intentionally scale-based, custom-property utilities when the value should be owned by a theme or component token, and arbitrary values when the class needs to encode exact CSS. Drop shadows deserve special care because a filter drop shadow follows the rendered alpha shape, while regular box shadows follow the element’s box. Likewise, blur and brightness can affect text legibility if applied to containers instead of media elements. Tailwind will generate the declaration for the class candidate, but the design responsibility remains deciding whether the filter belongs on an image, an icon, a wrapper, or an overlay.

When debugging missing output, start with the runtime boundary. In a CLI build, verify that the command is actually running a build and that the input source containing the class is reachable by the project setup. In the browser runtime, verify the Tailwind style tag type, remember that the main import is injected only when no import is present, and check whether the class was added after initialization. In Node integrations, inspect whether the integration calls the Node-facing compile surface and whether optimization or source maps are affecting how you inspect the result. Sources: packages/@tailwindcss-cli/src/index.ts, packages/@tailwindcss-browser/src/index.ts, packages/@tailwindcss-node/src/index.ts

Next Steps

Read the backdrop filter reference when the visual effect should apply to pixels behind an element rather than to the element itself. Continue to effects for shadows and opacity, transitions and animation for changing filters smoothly, responsive design for breakpoint prefixes, and the package API pages when you need to understand how compiler entry points are invoked by tools. If you are contributing behavior changes rather than only using the utilities, start from the core compiler source and validate through the root scripts that match the kind of change you made. Sources: packages/tailwindcss/src/index.ts, package.json