Shadows, Opacity, and Blend Modes
Purpose and Scope
Tailwind CSS groups visual rendering utilities under Effects so authors can change how an element is painted without leaving the utility-first workflow. In this page, an effect means a class that changes compositing, transparency, shadows, or blending rather than layout geometry or text flow. The practical reader problem is deciding which rendering property belongs on the element itself, which one belongs on a background layer, and how to make that choice conditional across states such as disabled controls, responsive breakpoints, or dark color schemes.
Opacity utilities control the transparency of the whole element, including descendants. Blend-mode utilities control how pixels combine with other pixels: mix blend mode compares an element with content behind it in the current stacking context, while background blend mode compares background image layers with background color on the same element. Shadow utilities belong in the same family because they alter perceived depth and elevation during painting, even though the supplied source evidence for this page focuses on variant composition instead of the shadow generator itself.
Tailwind’s first-party docs present these APIs as small class families that can be combined with variants. That is the important mental model for effects: the class name selects the CSS declaration, and a prefix such as a breakpoint, disabled state, or dark-mode state determines when that declaration participates in the final stylesheet. For example, an opacity choice can be unconditional for a default button, conditional for disabled inputs, responsive for larger screens, or tied to a dark-mode selector supplied by configuration.
Relevant Source Files
packages/tailwindcss/src/compat/dark-mode.ts— Registers thedarkvariant through the compatibility plugin API and shows how effect utilities can be conditionally applied under selector, media, custom variant, or legacy class-based dark-mode strategies.
Sources: packages/tailwindcss/src/compat/dark-mode.ts
Effect Utility Families
Opacity is the most direct effects utility family. The official syntax maps classes like opacity-25, opacity-75, and opacity-100 to percentage opacity declarations, and also supports arbitrary values and custom properties through bracket or parenthesized forms. Use this when the entire rendered element should fade together: backgrounds, borders, text, icons, and children all become transparent because the CSS property is inherited by painting behavior rather than applied only to a single visual layer.
A useful pattern is to keep the default state readable and reduce opacity only for a particular interaction state. The docs show this with a disabled input, where a normal field can stay fully opaque and the disabled state can receive a lower opacity through a state variant. This keeps visual state close to the markup and avoids writing a separate selector block. When the desired value is not on the standard numeric scale, arbitrary values support one-off choices such as fractional opacity, and custom-property shorthand makes design-token driven opacity concise.
Background blend mode is different because it is scoped to an element’s own background stack. Classes such as bg-blend-multiply, bg-blend-soft-light, bg-blend-overlay, and bg-blend-difference choose how a background image combines with a background color or other background layers. This is useful for hero images, cards, and decorative panels where the image and color are part of the same element. It does not describe how the element’s foreground text blends with neighboring content; it only affects background layers on that box.
Mix blend mode controls how the element itself blends with whatever is behind it. Classes such as mix-blend-multiply, mix-blend-overlay, and mix-blend-soft-light are appropriate for overlapping shapes, images, badges, and visual compositions where multiple sibling elements interact. The official docs call out isolate on a parent because blend modes otherwise participate in the surrounding stacking context. Creating a new stacking context is often the difference between an intentional two-element composition and a surprising interaction with unrelated page content behind the component.
Shadow utilities fit beside opacity and blend utilities because they express elevation and rendered depth. In practice, use a shadow class when the element should remain fully opaque but appear raised, use opacity when the whole element should fade, and use a blend-mode class when the element or its backgrounds should mathematically combine with colors underneath. This distinction helps prevent common mistakes, such as using opacity on a disabled button and accidentally fading nested text too far, or using mix blend mode when only a background image overlay was intended.
Conditional Effects and Variants
Effects become most useful when combined with variants, because visual feedback is usually stateful. The repository’s dark-mode compatibility plugin demonstrates the same variant mechanism that effects classes use when prefixed with dark:. The plugin receives addVariant and config from the plugin API, reads darkMode configuration, normalizes the requested mode and selector, validates custom variant formats, and then registers the dark variant differently depending on the selected strategy. That registration is what allows an ordinary utility, including an opacity or blend-mode class, to be emitted inside the right selector or media query.
Sources: packages/tailwindcss/src/compat/dark-mode.ts
The supported dark-mode strategies are important when designing effect-heavy components. With selector mode, the plugin registers a selector using :where, so a dark-mode class can respond to a configured dark selector and its descendants. With media mode, it registers a media query for the user’s preferred color scheme. With variant mode, a custom selector or selector list can be supplied, but formats must include the utility placeholder so Tailwind can place the generated rule correctly. Legacy class mode is still handled through a class-descendant selector for compatibility.
For an effects API user, this means conditional rendering choices are not special cases inside the opacity or blend utility itself. A class such as dark:opacity-75 or md:bg-blend-darken is a candidate composed from a variant prefix and a base utility. The base utility defines the declaration, while the variant system decides where that declaration lives in the compiled CSS. This separation keeps the effects reference small and predictable while allowing the same class family to work across responsive breakpoints, pseudo-classes, media queries, and configured dark-mode selectors.
Compact Reference
| Family | Example classes | CSS property | Use when | Notes |
|---|---|---|---|---|
| Opacity | opacity-25, opacity-75, opacity-100, opacity-[.67], opacity-(--my-opacity) | opacity | The entire element should become more or less transparent. | Custom-property syntax is shorthand for wrapping the token in var(). |
| Background blend mode | bg-blend-multiply, bg-blend-soft-light, bg-blend-overlay, bg-blend-luminosity | background-blend-mode | Background image layers should blend with a background color or with each other. | Use for image overlays and decorative panels. |
| Mix blend mode | mix-blend-multiply, mix-blend-overlay, mix-blend-difference, mix-blend-plus-lighter | mix-blend-mode | The element should blend with content behind it in the same stacking context. | Add isolate to a parent when the blend should not leak into surrounding page content. |
| Shadows | Shadow utility family | shadow-related CSS output | The element should appear elevated or separated without fading its contents. | Prefer shadows for depth, opacity for fading, and blend modes for color compositing. |
A typical opacity example keeps the default state clear and changes only the exceptional state. The class string opacity-100 disabled:opacity-75 says that the element is normally fully visible, then becomes visually subdued when disabled. A responsive example such as opacity-50 md:opacity-100 says that the same element starts quieter on small screens and becomes fully visible at the medium breakpoint and above. These examples illustrate the general Tailwind convention: variants are prefixes, and the final segment is the utility that owns the CSS declaration.
For backgrounds, combine the blend utility with an image and a color on the same element. A class string such as bg-blue-500 bg-[url(/img/mountains.jpg)] bg-blend-multiply tells the browser to paint the blue background and image together using multiply compositing. For responsive art direction, a breakpoint variant can swap the blend calculation later, such as moving from a lighter mobile overlay to a darker desktop overlay. The underlying background image and color utilities remain separate, so the blend utility only answers the compositing question.
For mix blending, think in terms of neighbors rather than background layers. Overlapping elements with mix-blend-multiply can create a combined color where they intersect, but they may also interact with page content outside the intended component. The official guidance to add isolate to the parent is therefore not just a visual tweak; it creates a boundary for compositing. Use that boundary when building reusable components so their blend behavior stays local and does not depend on whatever happens to be rendered behind the component on a particular page.
System-to-Code Mapping
The source file on this page does not enumerate opacity or blend classes; instead, it anchors how those classes become state-aware through Tailwind’s plugin and variant infrastructure. darkModePlugin reads configuration using config('darkMode', null), derives a mode and selector, and registers dark through addVariant. Because utilities are compiled after candidates are parsed with their variant prefixes, this registration is enough for visual effect classes to participate in dark-mode styling without each effect family having a custom dark-mode implementation.
Sources: packages/tailwindcss/src/compat/dark-mode.ts
The code also shows compatibility behavior that matters when documenting examples. If dark mode is configured as a custom variant, the plugin accepts arrays, functions, or strings as selector formats. It warns when a plain .dark selector is supplied for variant mode or when a selector does not contain the placeholder needed to position generated rules. Those checks protect authors from configurations that would make prefixed utilities ambiguous. In user-facing terms, a dark-mode effect should be written only after the project has a dark-mode strategy that can actually target the generated rule.
The selector and media branches explain why the same markup can support different application architectures. A content site might prefer a class or data selector controlled by a theme toggle, while an application might use the system preference media query. Tailwind keeps the effect utility unchanged in both cases. The class that controls opacity, blending, or shadow remains the base utility, and only the registered variant changes the wrapper. This is the same compositional model used across the framework, so learning it once applies to the rest of the utility reference.
Implementation Guidance and Next Steps
Choose the narrowest effect that expresses the visual goal. If a card needs softer presence, opacity may be correct, but remember that it affects every descendant. If only an image overlay needs different color interaction, prefer background blend mode. If two foreground elements should visually interact, use mix blend mode and deliberately decide whether the parent should be isolated. If the design calls for elevation rather than transparency or compositing, use shadow utilities so text and child controls remain fully legible.
When writing reusable components, include variants in the class string only when the state is part of the component contract. A disabled form control can own disabled:opacity-75, while a layout-level art direction decision may belong in the page using responsive bg-blend-* classes. For theme-aware effects, confirm the project’s dark-mode strategy first, then compose dark: with the base effect utility. Next, read the pages on hover and focus states, dark mode, backgrounds, filters, and transforms to understand adjacent rendering utilities and how variants compose across them.