CSS background-position-y Property

If this site has been useful, we’d love your support! Consider buying us a coffee to keep things going strong!

Description

The background-position-y property in CSS allows developers to control the vertical placement of a background image within an element independently of its horizontal position. While background-position sets both horizontal and vertical positions simultaneously, background-position-y isolates the vertical axis, enabling precise alignment along the top-to-bottom dimension of a container. This is particularly useful for elements with fixed heights or when designers want specific parts of an image - such as a logo or decorative detail - to remain visible, regardless of horizontal alignment. By specifying how far from the top or bottom an image should be positioned, this property ensures a consistent visual layout across different screen sizes and element dimensions.

One practical use of background-position-y is in creating responsive designs where the vertical focus of a background image needs adjustment based on viewport size. For example, a hero section might require the center of an image to remain visible on mobile devices while showing more of the top portion on larger screens. Adjusting background-position-y allows for these changes without needing multiple image assets or altering the horizontal alignment. Additionally, it can be combined with CSS animations to produce vertical movement effects, such as scrolling backgrounds or subtle parallax effects, enhancing the interactivity and depth of a webpage.

background-position-y also works in tandem with other background properties to control the overall presentation of images. When paired with background-repeat, developers can control whether a vertically repeated image aligns correctly within its container, avoiding awkward tiling or clipping. Similarly, when used alongside background-size, it allows designers to shift the focal point of a scaled image vertically, maintaining visual balance and emphasis. In essence, background-position-y provides fine-tuned control over vertical alignment, helping create visually cohesive and flexible designs that adapt seamlessly to different layouts and device sizes.

Definition

Initial value: 0%
Applies to: all elements
Inherited: no
Computed value: A list, each item consisting of: an offset given as a combination of an absolute length and a percentage, plus an origin keyword
Animatable: a repeatable list
JavaScript syntax: object.style.backgroundPositionY

Interactive Demo

background-position-y: left;

background-position-y: center;

background-position-y: right;

background-position-y: 3.5rem;

background-position-y: 35%;

Syntax

background-position-x: top | center | bottom | <percentage> | <size>

Values

topAligns the background to the top edge. Equivalent to writing 0 or 0%.
centerAligns the background to the vertical center. Equivalent to 50% entry.
bottomAligns the background to the bottom edge. Record equivalent to 100%.
<percentage>Sets the background position as a percentage of the elements height. A value of 0% or 0 aligns the top edge of the background image to the top edge of the element. A value of 100% aligns the bottom edge of the picture with the bottom edge of the element.
<size>Sets the position of the background in any units available for CSS - pixels (px), centimeters (cm), em, etc. relative to the top edge of the element.

Example

HTML

<div class='wrap'>

    <div class='box top'>

        <span class='label'>background-position-y: top</span>

    </div>

    <div class='box center'>

        <span class='label'>background-position-y: center</span>

    </div>

    <div class='box bottom'>

        <span class='label'>background-position-y: bottom</span>

    </div>

</div>

CSS

/* Demo: vertical background positioning */
* { box-sizing: border-box; }
.wrap {
    display: flex;
    gap: 16px;
    align-items: flex-start;
    padding: 24px;
    background: #f5f7fa;
    min-height: 100vh;
}
.box {
    width: 320px;
    height: 180px;
    border-radius: 8px;
    overflow: hidden;
    position: relative;
    background-image: url('https://images.unsplash.com/photo-1503264116251-35a269479413?auto=format&fit=crop&w=800&q=60');
    background-position-x: center;
    background-size: auto 150%;
    background-repeat: no-repeat;
    box-shadow: 0 4px 10px rgba(0,0,0,0.08);
}
.box.top { background-position-y: top; }
.box.center { background-position-y: center; }
.box.bottom { background-position-y: bottom; }
.label {
    position: absolute;
    left: 12px;
    bottom: 12px;
    padding: 6px 10px;
    background: rgba(0,0,0,0.6);
    color: #fff;
    font-family: system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial;
    font-size: 14px;
    border-radius: 4px;
}

Result

Editor

Browser Support

The following information will show you the current browser support for the CSS background-position-y property. Hover over a browser icon to see the version that first introduced support for this CSS property.