---
title: Background patterns
summary: Use background pattern utilities to add subtle textures to elements. Combine pattern type, color, and size modifiers for different visual effects.
description: Add decorative background patterns with utility classes.
added-in: '1.5.0'
related: [/ui/utilities/gradients]
---

import Example from '@components/Example.astro'
import Illustration from '@ui/Illustration.astro'
import site from '@data/site.json'
export const patterns = ['diagonal', 'diagonal-2', 'dots', 'rectangles', 'lines', 'lines-vertical', 'grid', 'grid-diagonal', 'blueprint', 'cross-dots', 'circles', 'diagonal-stripes', 'diagonal-stripes-2', 'zigzag', 'vertical-stripes', 'horizontal-stripes']
export const colors = Object.entries(site.colors)

## Overview

Background pattern utilities let you apply decorative, repeatable textures to elements like cards, sections, and placeholders. Start with a pattern type class, then optionally combine it with color and size modifiers.

```html
<div class="bg-pattern-diagonal"></div>
<div class="bg-pattern-grid bg-pattern-primary"></div>
<div class="bg-pattern-circles bg-pattern-lg"></div>
```

## Pattern types

Use one of the available pattern classes to define the shape and direction of the texture:

<ul>
  {patterns.map((pattern) => (
    <li>
      <code>.bg-pattern-{pattern}</code>
    </li>
  ))}
</ul>

Here are the available pattern types:

<Example hideCode>

<div class="row row-cols-1 row-cols-sm-2 row-cols-lg-3 row-cols-xl-4 g-3">
	{patterns.map((pattern, i) => {
		return (
			<div class="col">
				<div class={`bg-pattern-${pattern} border rounded mb-2`} style={{height: "6rem"}}></div>
				<code>.bg-pattern-{ pattern }</code>
			</div>
		)
	})}
</div>
</Example>
<Example codeOnly>
	{patterns.map((pattern) => (
		<div class={`bg-pattern-${pattern}`}></div>
	))}
</Example>

## Pattern colors

Combine any pattern with color modifiers using `.bg-pattern-{color}`. See the [full list of available colors](/ui/base/colors) for all color names.

<Example hideCode>

<div class="row row-cols-1 row-cols-sm-2 row-cols-lg-3 row-cols-xl-6 g-3">

{colors.map((color) => ( <div class="col"> <div class={`bg-pattern-diagonal-stripes-2 bg-pattern-${color[0]} border rounded mb-2`} style={{height: "6rem"}}></div> <code>.bg-pattern-{ color[0] }</code> </div> ))}

</div>
</Example>
<Example codeOnly>
	{colors.map((color) => (
		<div class={`bg-pattern-diagonal-stripes-2 bg-pattern-${color[0]}`}></div>
	))}
</Example>

## Transparent pattern utility

Use `.bg-pattern-transparent` when you need a checkerboard-style transparent background. Combine it with spacing and border classes. You can change strength with `--tblr-pattern-opacity` (include the `%` unit).

<Example hideCode>
  <Illustration image="boy-with-key.svg" class="d-block mx-auto mw-100" height={200} />
</Example>
<Example codeOnly>
  <div class="bg-pattern-transparent p-4"></div>
</Example>

## Pattern sizes

Use size utilities to control pattern density:

- `.bg-pattern-sm`
- `.bg-pattern-md`
- `.bg-pattern-lg`
- `.bg-pattern-xl`

Look at the following examples to see how the pattern sizes work:

<Example hideCode>
  <div class="row row-cols-1 row-cols-sm-2 row-cols-lg-4 g-3">
    <div class="col">
      <div class="bg-pattern-circles bg-pattern-sm border rounded mb-2" style="height: 6rem;"></div>
      <code>.bg-pattern-sm</code>
    </div>
    <div class="col">
      <div class="bg-pattern-circles bg-pattern-md border rounded mb-2" style="height: 6rem;"></div>
      <code>.bg-pattern-md</code>
    </div>
    <div class="col">
      <div class="bg-pattern-circles bg-pattern-lg border rounded mb-2" style="height: 6rem;"></div>
      <code>.bg-pattern-lg</code>
    </div>
    <div class="col">
      <div class="bg-pattern-circles bg-pattern-xl border rounded mb-2" style="height: 6rem;"></div>
      <code>.bg-pattern-xl</code>
    </div>
  </div>
</Example>
<Example codeOnly>
  <div class="bg-pattern-circles bg-pattern-sm"></div>
  <div class="bg-pattern-circles bg-pattern-md"></div>
  <div class="bg-pattern-circles bg-pattern-lg"></div>
  <div class="bg-pattern-circles bg-pattern-xl"></div>
</Example>

## Pattern opacity

Use opacity utilities to control how strong the texture is:

- `.bg-pattern-opacity-lighter`
- `.bg-pattern-opacity-light`
- `.bg-pattern-opacity-dark`
- `.bg-pattern-opacity-darker`

<Example hideCode>
  <div class="row row-cols-1 row-cols-sm-2 row-cols-lg-4 g-3">
    <div class="col">
      <div class="bg-pattern-circles bg-pattern-opacity-lighter border rounded mb-2" style="height: 6rem;"></div>
      <code>.bg-pattern-opacity-lighter</code>
    </div>
    <div class="col">
      <div class="bg-pattern-circles bg-pattern-opacity-light border rounded mb-2" style="height: 6rem;"></div>
      <code>.bg-pattern-opacity-light</code>
    </div>
    <div class="col">
      <div class="bg-pattern-circles bg-pattern-opacity-dark border rounded mb-2" style="height: 6rem;"></div>
      <code>.bg-pattern-opacity-dark</code>
    </div>
    <div class="col">
      <div class="bg-pattern-circles bg-pattern-opacity-darker border rounded mb-2" style="height: 6rem;"></div>
      <code>.bg-pattern-opacity-darker</code>
    </div>
  </div>
</Example>
<Example codeOnly>
  <div class="bg-pattern-circles bg-pattern-opacity-lighter"></div>
  <div class="bg-pattern-circles bg-pattern-opacity-light"></div>
  <div class="bg-pattern-circles bg-pattern-opacity-dark"></div>
  <div class="bg-pattern-circles bg-pattern-opacity-darker"></div>
</Example>

## Examples

Look at the following examples to see how background patterns can be used in real layouts.

### Card on a background pattern

Placing a card on a patterned background adds a decorative touch to the surrounding area while keeping the card itself clean. Wrap the card in an element with a `.bg-pattern-*` class so the pattern shows around the card without affecting the readability of its content.

<Example hideCode class="bg-pattern-diagonal">
  <div class="card">
    <div class="card-body">Here is an example of a card placed on a background pattern.</div>
  </div>
</Example>
<Example codeOnly>
  <div class="bg-pattern-diagonal">
    <div class="card">...</div>
  </div>
</Example>

## Accessibility

Background patterns are decorative and should never reduce content readability:

- Keep sufficient contrast between text and background.
- Prefer placing patterns on containers around text-heavy content, not directly behind long paragraphs.
- For callouts and alerts, test color and pattern combinations in both light and dark contexts.

## Best practices

- Start with `.bg-pattern-sm` for dense UIs and increase size only when needed.
- Avoid stacking multiple decorative backgrounds in the same section.
- Use strong pattern colors on small surfaces (headers, badges, callouts), and subtler combinations on large sections.