CSS background-position-y Property

This property sets the vertical starting position for a background image. It allows you to move the image up or down within its element without affecting the horizontal alignment.

selector { background-position-y: value; }

top	Aligns the top edge of the image with the top edge of the container.
center	Centers the image vertically within the container.
bottom	Aligns the bottom edge of the image with the bottom edge of the container.
<percentage>	Offsets the vertical position based on a percentage of the container's height minus the image's height.
<length>	Sets a fixed vertical offset from the top edge using units like px, em, or rem.
y-start	Aligns the image to the start of the vertical axis based on writing direction.
y-end	Aligns the image to the end of the vertical axis based on writing direction.

Code Examples

A basic example showing a background image vertically aligned to the bottom of its container using a keyword.

<div style="width: 300px; height: 300px; border: 2px solid #333333; background-image: url('https://www.adamkhoury.com/images/adam_khoury_logo.png'); background-repeat: no-repeat; background-position-y: bottom;"></div>

An advanced example using JavaScript to update the background-position-y property during a scroll event to create a parallax effect.

<div id="hero" style="width: 100%; height: 400px; background-image: url('https://www.adamkhoury.com/images/p1.jpg'); background-size: cover; background-position-x: center; background-position-y: 0%; border: 5px solid #000000;"></div>
<script>
window.addEventListener("scroll", function() {
    let box = document.getElementById("hero");
    let scrollPos = window.pageYOffset;
    box.style.backgroundPositionY = (scrollPos * 0.5) + "px";
});
</script>

Pro Tip

You can use the calc() function to create precise offsets from the bottom. For example, background-position-y: calc(100% - 20px); will place your image 20 pixels away from the bottom edge, which is much easier than guessing percentages.

Deep Dive

Think of the background-position-y property like a vertical scrollbar for a picture inside a frame. You aren't moving the frame itself, just sliding the picture up or down behind it. While the shorthand background-position property handles both X and Y, this property targets only the Y-axis. When using length values like 20px, the top of the image sits exactly 20 pixels from the top of the element. Percentage values are more specialized: 0% is the top, 100% is the bottom, and 50% is the center. The browser calculates the percentage by looking at the difference between the container height and the image height, ensuring that 100% actually shows the bottom of the image rather than pushing it out of view.

Best Practices

Use this property when you need to specifically override or animate only the vertical axis of a background image. It is cleaner than re-declaring the full background-position shorthand when the horizontal value should remain unchanged. It is especially useful in responsive design where you might want to nudge an image vertically as the screen height changes.

Common Pitfalls

A common point of confusion is how percentages work. Unlike pixels, which measure from the top edge, a percentage value like 50% aligns the 50% vertical point of the image with the 50% vertical point of the container. If your image is larger than the container, using a negative length value will move it up, but beginners often try to use positive values to move things up, which actually pushes them down.

Accessibility

Background images are usually decorative, but if your image moves via user interaction or animation, ensure it doesn't cause high-contrast text to become unreadable. Never put critical information inside a background image, as screen readers generally ignore them. If the vertical position change creates a flashing effect, it could trigger issues for users with motion sensitivity.

Dev Data Table: background-position-y property

default	0%
animatable	yes
inherited	no
experimental	no
year_intro	2004
year_standard	2021
js_syntax_1	element.style.backgroundPositionY = "50%";
js_syntax_2	element.style.setProperty("background-position-y", "50%");
js_note	When manipulating this property in JavaScript, use camelCase for the style object property or the hyphenated string for the setProperty method.
browsers	{ "Chrome": 1, "Edge": 12, "Firefox": 49, "Safari": 1, "Opera": 15, "Chrome Android": 18, "Safari on iOS": 1, "Samsung Internet": 1, "Opera Mobile": 14 }