Backgrounds
Purpose and Scope
Tailwind background utilities give authors a compact vocabulary for controlling an element’s painted backdrop: color, image layers, scroll attachment, clipping area, positioning, repetition, sizing, and the way images blend with color. In day-to-day use, these utilities are usually combined rather than chosen in isolation. A card might use bg-blue-500 for a fallback color, bg-[url(/img/mountains.jpg)] for an image, bg-cover to fill the container, bg-center for alignment, and bg-blend-multiply to combine the image with the color layer. The reader problem this page solves is understanding that family as one coherent API rather than as separate CSS properties.
The first-party documentation presents background size, attachment, and background blend mode as utility references, and the same naming pattern extends across the rest of the background family. Static keywords map directly to CSS declarations, while arbitrary values allow one-off CSS values when a design needs something outside the theme. Color-related background utilities also participate in Tailwind’s theme system. The compiler has to turn nested color palettes into class-name suffixes and decide when an arbitrary token is a color value. Those two implementation concerns are represented by the repository source files for palette flattening and color detection.
Sources: packages/tailwindcss/src/compat/flatten-color-palette.ts, packages/tailwindcss/src/utils/is-color.ts
Relevant Source Files
packages/tailwindcss/src/compat/flatten-color-palette.ts— flattens nested color objects into the dash-separated keys used by color utility families such asbg-sky-500, while preserving the special handling forDEFAULTand internal CSS-value metadata.packages/tailwindcss/src/utils/is-color.ts— recognizes CSS color inputs by hash prefix, supported color functions, named colors, keywords, and system colors; this helps Tailwind distinguish color-like arbitrary values from other arbitrary background values.
Background Utility Families
Background color utilities are the most common entry point into this family. They use the bg-* namespace together with the theme color palette, so a nested palette entry such as a sky scale can become class names like bg-sky-500, and a DEFAULT shade can become the root color name without an extra suffix. In the compatibility helper, flattenColorPalette recursively walks a color object, skips the internal __CSS_VALUES__ key during the normal traversal, joins nested keys with hyphens, and treats DEFAULT as the value that should not add another segment. That explains why the public class naming feels natural even when the theme data is nested.
Background image utilities set image layers rather than colors. The official examples use arbitrary URL values such as bg-[url(/img/mountains.jpg)], which lets a template declare an image without adding a named theme entry first. Once an image is present, the other background utilities describe how that image behaves. bg-fixed, bg-local, and bg-scroll map to background-attachment values, controlling whether the image is fixed to the viewport, scrolls with the element’s content, or scrolls with the viewport while remaining fixed in the element’s background painting area. These classes are especially useful on long content panels where scroll behavior is visible.
Sizing utilities describe how background images fit the box. The documented static forms are bg-auto, bg-cover, and bg-contain, corresponding to the CSS values auto, cover, and contain. bg-cover fills the background layer and may crop the image; bg-contain fits the image inside the area without cropping; bg-auto keeps the image at its intrinsic size. Tailwind also supports arbitrary size syntax such as bg-size-[auto_100px] and custom-property shorthand like bg-size-(--my-image-size), where the shorthand represents var(--my-image-size) for the generated CSS value.
Position, repeat, origin, clip, and attachment utilities are usually paired with image and size utilities to remove ambiguity from the rendered result. A background image that uses bg-auto often also needs bg-no-repeat and a position such as bg-center, because the default CSS repetition and top-left positioning may not match the intended design. Clipping and origin utilities matter when borders, padding, and content boxes should affect where a background is painted or positioned. Treat these classes as the layout controls for background layers: they do not choose the asset, but they determine how that asset occupies the element box.
Background blend mode sits at the boundary between backgrounds and visual effects. The official docs list bg-blend-normal, bg-blend-multiply, bg-blend-screen, bg-blend-overlay, bg-blend-darken, bg-blend-lighten, color dodge and burn, hard and soft light, difference, exclusion, hue, saturation, color, and luminosity. These utilities set background-blend-mode, so they only become visible when there is something to blend, commonly a background color plus a background image. A practical pattern is bg-blue-500 bg-[url(/img/mountains.jpg)] bg-blend-multiply, where the color utility supplies one layer and the image supplies another.
System-to-Code Mapping
The important source-level connection for background colors is palette flattening. Tailwind’s theme configuration and CSS-first theme variables can represent colors in nested groups, but class candidates need a flat suffix format. The compatibility helper takes an object of colors, recurses through child objects, and emits keys like root-parent except when the child key is DEFAULT, where the emitted key is just the root. It also has a second pass for __CSS_VALUES__, using ThemeOptions.DEFAULT metadata to decide which values should override flattened results. That behavior is relevant when older configuration conventions and generated CSS theme values need to coexist.
Color recognition is the second relevant implementation point. The isColor utility accepts values that start with #, values that look like supported CSS color functions, and values that match a named-color set after lowercasing. The function-pattern includes common forms such as rgb(), rgba(), hsl(), hsla(), hwb(), color(), lab(), lch(), oklab(), oklch(), light-dark(), color-mix(), and Tailwind’s --alpha() helper form. The named-color table includes legacy CSS colors, transparent, currentcolor, and system colors such as canvas, canvastext, and accentcolor. This matters for arbitrary values because bg-[red], bg-[#0ea5e9], and bg-[color-mix(...)] need to be understood as colors, not as background image or size values.
Sources: packages/tailwindcss/src/compat/flatten-color-palette.ts, packages/tailwindcss/src/utils/is-color.ts
Compact Reference
| Utility area | Example classes | CSS concept | Notes |
|---|---|---|---|
| Background color | bg-blue-500, bg-transparent, bg-[oklch(70%_0.2_250)] | background-color | Theme colors rely on flattened palette keys; arbitrary colors rely on color detection. |
| Background image | bg-[url(/img/mountains.jpg)] | background-image | Commonly combined with size, position, repeat, and blend utilities. |
| Attachment | bg-fixed, bg-local, bg-scroll | background-attachment | Controls how the image behaves during viewport or container scrolling. |
| Size | bg-auto, bg-cover, bg-contain, bg-size-[auto_100px], bg-size-(--my-image-size) | background-size | Static values cover common image fitting; arbitrary and custom-property syntax covers custom sizes. |
| Position and repeat | bg-center, bg-no-repeat | background-position, background-repeat | Often paired with bg-auto, bg-cover, or arbitrary image values. |
| Origin and clip | bg-origin-*, bg-clip-* | background-origin, background-clip | Determine which box is used for positioning and painting. |
| Blend mode | bg-blend-multiply, bg-blend-overlay, bg-blend-luminosity | background-blend-mode | Requires multiple visible background layers to show an effect. |
Authoring Flow
Start by deciding whether the background is primarily a color, an image, or a layered composition. For a plain surface, choose a theme-backed color utility such as bg-slate-900 or a semantic custom color from your project’s theme. For an image-backed surface, add the image first, then make its fitting explicit with bg-cover, bg-contain, or bg-auto. Next, set the position and repeat behavior so the result remains predictable across different element sizes. Finally, add attachment or blend utilities only when those effects are part of the interaction or art direction, because they can change scroll perception and contrast.
A typical hero section might begin as bg-[url(/img/mountains.jpg)] bg-cover bg-center. If the image needs a color treatment, layer in bg-blue-500 bg-blend-multiply. If the same image should retain its intrinsic dimensions for a decorative panel, use bg-auto bg-center bg-no-repeat instead. For responsive design, background utilities can be prefixed with breakpoint variants, as shown in the official examples with forms like md:bg-contain or md:bg-blend-darken. This keeps the class local to the element while still expressing that the background behavior changes at a particular viewport size.
Use arbitrary values when the CSS value is specific to one component and does not deserve a theme token. Use named or theme colors when the value participates in a broader design system. The repository’s isColor helper is a useful mental model for what counts as a color-like arbitrary value: hex notation, modern CSS color functions, named colors, transparent, currentcolor, and system colors are all part of the supported recognition surface. For maintainability, prefer theme entries for repeated brand colors and reserve bg-[...] for asset URLs, experimental color functions, unusual sizes, or one-off CSS values.
Implementation Details
The palette flattener is intentionally small but important because it preserves public class naming across nested data shapes. It initializes an empty result object, iterates entries from the provided color object, recursively flattens child objects, and writes scalar values directly. The DEFAULT special case prevents redundant names, so a nested default color can be addressed with the same concise suffix authors expect. The later __CSS_VALUES__ pass shows that not every internal CSS value should blindly win; the code checks the ThemeOptions.DEFAULT bit before copying a value back into the flattened result.
The color detector is likewise conservative in shape but broad in vocabulary. It does not parse every CSS grammar production; instead, it checks the first character for a hash, tests the beginning of the string against a function-name regular expression, and falls back to membership in a normalized named-color set. That strategy is fast and sufficient for classification decisions inside a utility compiler, where the immediate question is often whether an arbitrary value should be routed as a color. The inclusion of modern functions such as oklch() and color-mix() aligns with Tailwind’s color-heavy workflows and current CSS authoring patterns.
Next Steps
For deeper background color customization, read the Theme and Colors pages next, because they explain how project-level color tokens become reusable utilities. For conditional backgrounds, pair this page with Responsive Design and Hover, Focus, and Other States so that classes like md:bg-cover, hover:bg-blue-600, or dark-mode background combinations are applied intentionally. If you are extending Tailwind with plugins or compatibility configuration, the Configuration and Plugin API page is the right follow-up, since it explains how custom utilities and theme values enter the compiler before helpers like palette flattening and color recognition are used.