CSS background-repeat Property

This property controls how a background image tiles within an element. It dictates whether an image repeats along the x-axis, y-axis, both, or not at all.

selector { background-repeat: value; }

repeat	Tiles the background image in both horizontal and vertical directions to cover the entire element.
repeat-x	Tiles the background image along the horizontal axis only.
repeat-y	Tiles the background image along the vertical axis only.
no-repeat	Displays the background image only once without any tiling or duplication.
space	Tiles the image as many times as possible without clipping, distributing extra whitespace evenly between the tiles.
round	Tiles the image and stretches or squashes the tiles so that an exact number of them fit perfectly within the container.

Code Examples

A basic example that tiles a background image horizontally across the top of a div container.

<div style="width: 100%; height: 150px; background-image: url('pattern.png'); background-repeat: repeat-x; border: 1px solid #000000;"></div>

An advanced example using JavaScript to toggle between a single centered image and a full tiled pattern when the user clicks the element.

<div id="stage" style="width: 100%; height: 400px; background-image: url('logo.png'); background-repeat: no-repeat; background-position: center; background-color: #f0f0f0; cursor: pointer;"></div>
<script>
const stage = document.getElementById("stage");
stage.addEventListener("click", function() {
    const isRepeat = stage.style.backgroundRepeat === "repeat";
    stage.style.backgroundRepeat = isRepeat ? "no-repeat" : "repeat";
    stage.style.backgroundColor = isRepeat ? "#f0f0f0" : "#cccccc";
});
</script>

Pro Tip

The round value is a secret weapon for responsive design. It prevents that ugly clipped-off image look at the edges of a container by automatically adjusting the image size to fit an integer number of times. It is like having a tile that magically grows or shrinks to fit the room perfectly without ever being cut in half.

Deep Dive

Think of background-repeat like laying floor tiles in a room. By default, the browser starts in the top-left corner and tiles the image across the entire floor until every inch is covered. You can tell the contractor to only lay one row of tiles along the wall (repeat-x) or one column (repeat-y). Newer values like space and round act like smart tiles; space will spread them out evenly so you don't have a cut tile at the edge, while round will slightly stretch them so they fit perfectly without gaps. You can also pass two values to handle the x and y axes independently, such as background-repeat: repeat no-repeat; which would tile horizontally but not vertically.

Best Practices

When using no-repeat, always pair it with a background-color that complements the image to ensure the design remains readable if the image fails to load. Use the shorthand background property for cleaner code if you are setting multiple background attributes at once. If you are creating patterns or textures, ensure the edges of your image are seamless to avoid visible lines when tiling.

Common Pitfalls

A common mistake is forgetting that repeat is the default setting, which can lead to unexpected tiling if your container grows larger than your image. Also, when using two-value syntax, the first value is for the horizontal axis and the second is for the vertical; getting these swapped is a frequent headache for developers.

Accessibility

Background images are purely decorative and are not perceived by screen readers. If your repeating pattern makes text hard to read, ensure there is enough contrast or a semi-transparent overlay between the background and the content. Never use a background image to convey critical information without providing a text alternative elsewhere.

Dev Data Table: background-repeat property

default	repeat
animatable	no
inherited	no
experimental	no
year_intro	1996
year_standard	1996
js_syntax_1	element.style.backgroundRepeat = "repeat-x";
js_syntax_2	element.style.setProperty("background-repeat", "no-repeat");
js_note	When targeting this property in JavaScript, use camelCase backgroundRepeat or the setProperty method with the kebab-case string.
browsers	{ "Chrome": 1, "Edge": 12, "Firefox": 1, "Safari": 1, "Opera": 3.5, "Chrome Android": 18, "Safari on iOS": 1, "Samsung Internet": 1, "Opera Mobile": 10 }