---
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.4.0'
source-css: 'ui/_patterns.scss'
---

{% assign 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" | split: "," %}

## 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:

{% for pattern in patterns %}
- `.bg-pattern-{{ pattern }}`
{% endfor %}

Here are the available pattern types:

{% capture html -%}

<div class="row row-cols-1 row-cols-sm-2 row-cols-lg-3 row-cols-xl-4 g-3">
  {% for pattern in patterns %}
  <div class="col">
    <div class="bg-pattern-{{ pattern }} rounded mb-2" style="height: 6rem;"></div>
    <code>.bg-pattern-{{ pattern }}</code>
  </div>
  {% endfor %}
</div>
{%- endcapture %}
{% capture code %}
{% for pattern in patterns -%}
<div class="bg-pattern-{{ pattern }}"></div>
{% endfor %}
{% endcapture %}
{% include "docs/example.html" html=html code=code bg="surface-primary" %}

## 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.

{% capture html -%}

<div class="row row-cols-1 row-cols-sm-2 row-cols-lg-3 row-cols-xl-6 g-3">
  {% for color in site.colors %}
  <div class="col">
    <div class="bg-pattern-diagonal-stripes-2 bg-pattern-{{ color[0] }} rounded mb-2" style="height: 6rem;"></div>
    <code>.bg-pattern-{{ color[0] }}</code>
  </div>
  {% endfor %}
</div>
{%- endcapture %}
{% capture code %}
{% for color in site.colors -%}
<div class="bg-pattern-diagonal-stripes-2 bg-pattern-{{ color[0] }}"></div>
{% endfor %}
{% endcapture %}
{% include "docs/example.html" html=html code=code bg="surface-primary" %}

## Transparent pattern utility

Use `.bg-pattern-transparent` when you need a checkerboard-style transparent background.
This utility comes from the generic background utilities and can be combined with spacing and border classes.

{% capture html -%}
{% include "ui/illustration.html" image="boy-with-key.svg" class="d-block mx-auto mw-100" height=200 %}
{%- endcapture %}
{% capture code %}
<div class="bg-pattern-transparent p-4">
  <!-- Illustration code here -->
</div>
{% endcapture %}
{% include "docs/example.html" html=html code=code bg="pattern-rectangles" column %}

## 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:

{% capture html -%}

<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 rounded mb-2" style="height: 6rem;"></div>
    <code>.bg-pattern-sm</code>
  </div>
  <div class="col">
    <div class="bg-pattern-circles bg-pattern-md rounded mb-2" style="height: 6rem;"></div>
    <code>.bg-pattern-md</code>
  </div>
  <div class="col">
    <div class="bg-pattern-circles bg-pattern-lg rounded mb-2" style="height: 6rem;"></div>
    <code>.bg-pattern-lg</code>
  </div>
  <div class="col">
    <div class="bg-pattern-circles bg-pattern-xl rounded mb-2" style="height: 6rem;"></div>
    <code>.bg-pattern-xl</code>
  </div>
</div>
{%- endcapture %}
{% capture code %}
<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>
{% endcapture %}
{% include "docs/example.html" html=html code=code bg="surface-primary" %}

## Examples

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

### Card with background pattern

Card with a background pattern in the body can be used to add a decorative touch to the card. This is useful when you want to add a subtle pattern to the card without affecting the readability of the content.

{% capture html -%}

<div class="card">
  <div class="card-body">
    Here is example of a card with a background pattern.
  </div>
</div>
{%- endcapture %}
{% capture code %}
<div class="bg-pattern-diagonal">
  <div class="card">
    ...
  </div>
</div>
{% endcapture %}
{% include "docs/example.html" html=html code=code bg="pattern-diagonal" column %}

## 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.