Skip to content
Tutorials Center
My learning

Topics

CSS Reference ยท Colors and Backgrounds

The background-position-y property

Reference for CSS background-position-y: vertical keywords, lengths, percentages and edge offsets, how it relates to background-position, and examples.

The background-position-y property is the vertical half of background-position. It moves each background image up or down inside its positioning area and leaves the horizontal position unchanged.

A typical use is cropping a tall photo in a short banner: background-position-y: 30% chooses which slice of the picture stays visible, without touching the horizontal alignment.

CSS
.banner { background-size: cover; background-position-y: 30%; }
.icon   { background-position-y: bottom 4px; }

Try it

Choosing the visible slice

Syntax

CSS
background-position-y: [ center | [ top | bottom ]? <length-percentage>? ]#;

background-position-y: 20px;
background-position-y: bottom 10px;
  • Initial value: 0%
  • Applies to: all elements
  • Inherited: no
  • Animatable: yes (lengths and percentages)
  • Computed value: a list of percentages or lengths, with keywords converted

Values

Value Description
top, center, bottom Aligns the image with the top edge, the middle or the bottom edge.
<length> Offset from the top edge. Negative values shift the image upward, out of the area.
<percentage> Aligns the point at that percentage of the image with the same point of the area.
top / bottom plus an offset Measures the offset from the chosen edge (bottom 10px).
Comma-separated list One value per layer.

Usage notes

  • A longhand of background-position. A later background-position declaration resets both axes.
  • Combine with cover. With background-size: cover the image usually overflows in one direction only. If it overflows vertically, background-position-y is the only axis that does anything visible.
  • Percentages need slack. If the image is the same height as the area, any percentage looks the same. The movement equals the percentage times the difference between area height and image height.
  • Keep faces and focal points in view. For responsive hero images, choose a value like 25% rather than center so the important part of the photo is not cropped on narrow or wide screens.
  • Physical, not logical. top and bottom are always physical, even in vertical writing modes.
  • Animation caution. Animating this property repaints the background each frame. Use sparingly, or move a pseudo-element with transform instead.

Browser support

Supported in current browsers. Check a compatibility table if you must support very old ones.