# Source: https://github.com/tailwindlabs/tailwindcss.com/blob/main/src/docs/background-position.mdx

import { ApiTable } from "@/components/api-table.tsx";
import { Example } from "@/components/example.tsx";
import { Figure } from "@/components/figure.tsx";
import { ResponsiveDesign, UsingACustomValue } from "@/components/content.tsx";

export const title = "background-position";
export const description = "Utilities for controlling the position of an element's background image.";

<ApiTable
  rows={[
    ["bg-top-left", "background-position: top left;"],
    ["bg-top", "background-position: top;"],
    ["bg-top-right", "background-position: top right;"],
    ["bg-left", "background-position: left;"],
    ["bg-center", "background-position: center;"],
    ["bg-right", "background-position: right;"],
    ["bg-bottom-left", "background-position: bottom left;"],
    ["bg-bottom", "background-position: bottom;"],
    ["bg-bottom-right", "background-position: bottom right;"],
    ["bg-position-(<custom-property>)", "background-position: var(<custom-property>);"],
    ["bg-position-[<value>]", "background-position: <value>;"],
  ]}
/>

## Examples

### Basic example

Use utilities like `bg-center`, `bg-right`, and `bg-top-left` to control the position of an element's background image:

<Figure hint="Hover over these examples to see the full image">

<Example padding={false}>
  {
    <div className="w-full">
      <div className="flex snap-x scroll-p-4 items-end overflow-x-scroll overflow-y-hidden p-8 pt-16 sm:grid sm:grid-cols-3 sm:gap-16">
        <div className="relative w-32 shrink-0 snap-start snap-always sm:w-auto">
          <p className="absolute inset-x-0 top-0 mb-3 -translate-y-8 text-center font-mono text-xs font-medium text-gray-500 dark:text-gray-400">
            bg-top-left
          </p>
          <div className="group relative mx-auto h-20 w-20 rounded-lg">
            <div className="relative z-10 h-full w-full rounded-md bg-[url(https://images.unsplash.com/photo-1554629947-334ff61d85dc?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1000&h=1000&q=90)] bg-[size:8rem] bg-top-left outline -outline-offset-1 outline-black/10"></div>
            <img
              className="absolute top-0 left-0 h-32 w-32 max-w-none overflow-hidden rounded-md opacity-0 sm:group-hover:opacity-25"
              src="https://images.unsplash.com/photo-1554629947-334ff61d85dc?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1000&h=1000&q=90"
            />
          </div>
        </div>
        <div className="relative w-32 shrink-0 snap-start snap-always sm:w-auto">
          <p className="absolute inset-x-0 top-0 mb-3 -translate-y-8 text-center font-mono text-xs font-medium text-gray-500 dark:text-gray-400">
            bg-top
          </p>
          <div className="group relative mx-auto h-20 w-20 rounded-lg">
            <div className="relative z-10 h-full w-full rounded-md bg-[url(https://images.unsplash.com/photo-1554629947-334ff61d85dc?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1000&h=1000&q=90)] bg-[size:8rem] bg-top outline -outline-offset-1 outline-black/10"></div>
            <img
              className="absolute top-0 -left-6 h-32 w-32 max-w-none overflow-hidden rounded-md opacity-0 sm:group-hover:opacity-25"
              src="https://images.unsplash.com/photo-1554629947-334ff61d85dc?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1000&h=1000&q=90"
            />
          </div>
        </div>
        <div className="relative w-32 shrink-0 snap-start snap-always sm:w-auto">
          <p className="absolute inset-x-0 top-0 mb-3 -translate-y-8 text-center font-mono text-xs font-medium text-gray-500 dark:text-gray-400">
            bg-top-right
          </p>
          <div className="group relative mx-auto h-20 w-20 rounded-lg">
            <div className="relative z-10 h-full w-full rounded-md bg-[url(https://images.unsplash.com/photo-1554629947-334ff61d85dc?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1000&h=1000&q=90)] bg-[size:8rem] bg-top-right outline -outline-offset-1 outline-black/10"></div>
            <img
              className="absolute top-0 right-0 h-32 w-32 max-w-none overflow-hidden rounded-md opacity-0 sm:group-hover:opacity-25"
              src="https://images.unsplash.com/photo-1554629947-334ff61d85dc?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1000&h=1000&q=90"
            />
          </div>
        </div>
        <div className="relative w-32 shrink-0 snap-start snap-always sm:w-auto">
          <p className="absolute inset-x-0 top-0 mb-3 -translate-y-8 text-center font-mono text-xs font-medium text-gray-500 dark:text-gray-400">
            bg-left
          </p>
          <div className="group relative mx-auto h-20 w-20 rounded-lg">
            <div className="relative z-10 h-full w-full rounded-md bg-[url(https://images.unsplash.com/photo-1554629947-334ff61d85dc?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1000&h=1000&q=90)] bg-[size:8rem] bg-left outline -outline-offset-1 outline-black/10"></div>
            <img
              className="absolute -top-6 left-0 h-32 w-32 max-w-none overflow-hidden rounded-md opacity-0 sm:group-hover:opacity-25"
              src="https://images.unsplash.com/photo-1554629947-334ff61d85dc?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1000&h=1000&q=90"
            />
          </div>
        </div>
        <div className="relative w-32 shrink-0 snap-start snap-always sm:w-auto">
          <p className="absolute inset-x-0 top-0 mb-3 -translate-y-8 text-center font-mono text-xs font-medium text-gray-500 dark:text-gray-400">
            bg-center
          </p>
          <div className="group relative mx-auto h-20 w-20 rounded-lg">
            <div className="relative z-10 h-full w-full rounded-md bg-[url(https://images.unsplash.com/photo-1554629947-334ff61d85dc?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1000&h=1000&q=90)] bg-[size:8rem] bg-center outline -outline-offset-1 outline-black/10"></div>
            <img
              className="absolute -top-6 -left-6 h-32 w-32 max-w-none overflow-hidden rounded-md opacity-0 sm:group-hover:opacity-25"
              src="https://images.unsplash.com/photo-1554629947-334ff61d85dc?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1000&h=1000&q=90"
            />
          </div>
        </div>
        <div className="relative w-32 shrink-0 snap-start snap-always sm:w-auto">
          <p className="absolute inset-x-0 top-0 mb-3 -translate-y-8 text-center font-mono text-xs font-medium text-gray-500 dark:text-gray-400">
            bg-right
          </p>
          <div className="group relative mx-auto h-20 w-20 rounded-lg">
            <div className="relative z-10 h-full w-full rounded-md bg-[url(https://images.unsplash.com/photo-1554629947-334ff61d85dc?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1000&h=1000&q=90)] bg-[size:8rem] bg-right outline -outline-offset-1 outline-black/10"></div>
            <img
              className="absolute -top-6 right-0 h-32 w-32 max-w-none overflow-hidden rounded-md opacity-0 sm:group-hover:opacity-25"
              src="https://images.unsplash.com/photo-1554629947-334ff61d85dc?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1000&h=1000&q=90"
            />
          </div>
        </div>
        <div className="relative w-32 shrink-0 snap-start snap-always sm:w-auto">
          <p className="absolute inset-x-0 top-0 mb-3 -translate-y-8 text-center font-mono text-xs font-medium text-gray-500 dark:text-gray-400">
            bg-bottom-left
          </p>
          <div className="group relative mx-auto h-20 w-20 rounded-lg">
            <div className="relative z-10 h-full w-full rounded-md bg-[url(https://images.unsplash.com/photo-1554629947-334ff61d85dc?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1000&h=1000&q=90)] bg-[size:8rem] bg-bottom-left outline -outline-offset-1 outline-black/10"></div>
            <img
              className="absolute -top-12 left-0 h-32 w-32 max-w-none overflow-hidden rounded-md opacity-0 sm:group-hover:opacity-25"
              src="https://images.unsplash.com/photo-1554629947-334ff61d85dc?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1000&h=1000&q=90"
            />
          </div>
        </div>
        <div className="relative w-32 shrink-0 snap-start snap-always sm:w-auto">
          <p className="absolute inset-x-0 top-0 mb-3 -translate-y-8 text-center font-mono text-xs font-medium text-gray-500 dark:text-gray-400">
            bg-bottom
          </p>
          <div className="group relative mx-auto h-20 w-20 rounded-lg">
            <div className="relative z-10 h-full w-full rounded-md bg-[url(https://images.unsplash.com/photo-1554629947-334ff61d85dc?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1000&h=1000&q=90)] bg-[size:8rem] bg-bottom outline -outline-offset-1 outline-black/10"></div>
            <img
              className="absolute -top-12 -left-6 h-32 w-32 max-w-none overflow-hidden rounded-md opacity-0 sm:group-hover:opacity-25"
              src="https://images.unsplash.com/photo-1554629947-334ff61d85dc?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1000&h=1000&q=90"
            />
          </div>
        </div>
        <div className="relative -mx-8 w-48 shrink-0 snap-start snap-always sm:w-auto">
          <p className="absolute inset-x-0 top-0 mb-3 -translate-y-8 text-center font-mono text-xs font-medium text-gray-500 dark:text-gray-400">
            bg-bottom-right
          </p>
          <div className="group relative mx-auto h-20 w-20 rounded-lg">
            <div className="relative z-10 h-full w-full rounded-md bg-[url(https://images.unsplash.com/photo-1554629947-334ff61d85dc?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1000&h=1000&q=90)] bg-[size:8rem] bg-bottom-right outline -outline-offset-1 outline-black/10"></div>
            <img
              className="absolute -top-12 right-0 h-32 w-32 max-w-none overflow-hidden rounded-md opacity-0 sm:group-hover:opacity-25"
              src="https://images.unsplash.com/photo-1554629947-334ff61d85dc?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1000&h=1000&q=90"
            />
          </div>
        </div>
      </div>
    </div>
  }
</Example>

```html
<!-- [!code classes:bg-top-left,bg-top-right,bg-bottom-right,bg-bottom-left,bg-center,bg-right,bg-top,bg-bottom,bg-left] -->
<div class="bg-[url(/img/mountains.jpg)] bg-top-left"></div>
<div class="bg-[url(/img/mountains.jpg)] bg-top"></div>
<div class="bg-[url(/img/mountains.jpg)] bg-top-right"></div>
<div class="bg-[url(/img/mountains.jpg)] bg-left"></div>
<div class="bg-[url(/img/mountains.jpg)] bg-center"></div>
<div class="bg-[url(/img/mountains.jpg)] bg-right"></div>
<div class="bg-[url(/img/mountains.jpg)] bg-bottom-left"></div>
<div class="bg-[url(/img/mountains.jpg)] bg-bottom"></div>
<div class="bg-[url(/img/mountains.jpg)] bg-bottom-right"></div>
```

</Figure>

### Using a custom value

<UsingACustomValue utility="bg-position" value="center_top_1rem" name="background position" variable="bg-position" />

### Responsive design

<ResponsiveDesign property="background-position" defaultClass="bg-center" featuredClass="bg-top" />