CSS <position> Data Type

The CSS <position> data type is used for positioning within a two-dimensional space.

The <position> data type was initially defined to be used with the background-position property, in order to position background images. It has since been included in other CSS features, such as the radial-gradient() function, where it defines the position of the gradient's center.

When you see <position> (including the < and >) anywhere in the CSS specifications, this refers to the fact that the value can be any valid position.

For example, the background-position property accepts the following values:

Which means that you must provide at least one position (and optionally a second position).

Note that the official syntax for the <position> data type is:

So you can use keywords such as left or top to specify the position, or you can use a <percentage> or <length>.

You can also combine certain keywords. For example, top left or bottom right.

You can even combine keywords with a <percentage> or <length> value to define an offset. For example, top 10px is 10 pixels down from the top.

The first value defines the horizontal position and the second defines the vertical position. If only one position is provided, the second value is assumed to be center.

Positioning Background Images

So all of the following are valid <position> values when positioning a background image:

The following two examples use the same background images, but with different <position> values.

`top left`

<style>
  div {
    height: 200px;
    background-color: beige;
    background-image: url(/pix/samples/bg2.png);
    background-repeat: no-repeat;
    background-position: top left;
  }
</style>
<div></div>

`bottom right`

<style>
  div {
    height: 200px;
    background-color: beige;
    background-image: url(/pix/samples/bg2.png);
    background-repeat: no-repeat;
    background-position: bottom right;
  }
</style>
<div></div>

If three or four values are given, then each <percentage> or <length> represents an offset and must be preceded by a keyword, which specifies from which edge the offset is given.

Like this:

<style>
  div {
    height: 200px;
    background-color: beige;
    background-image: url(/pix/samples/bg2.png);
    background-repeat: no-repeat;
    background-position: bottom 10% right 20%;
  }
</style>
<div></div>

Positioning Gradients

When using the radial-gradient() function, the <position> values must be preceded by the at keyword.

Like this:

Which will result in this:

<style>
  div {
    background: radial-gradient(at bottom right, yellow, red);
    color: white;
    padding: 30px;
    height: 160px;
    font-family: sans-serif;
    font-size: 1.5em;
  }
</style>

<div>
  Radial gradient example.
</div>

Accepted Values

The <position> type can use any of the following values.

<percentage>: Provides a percentage for the horizontal offset.
<length>: Provides a fixed length as the offset.
top: Computes to 0% for the vertical position if one or two values are given, otherwise specifies the top edge as the origin for the next offset.
right: Computes to 100% for the horizontal position if one or two values are given, otherwise specifies the right edge as the origin for the next offset.
bottom: Computes to 100% for the vertical position if one or two values are given, otherwise specifies the bottom edge as the origin for the next offset.
left: Computes to 0% for the horizontal position if one or two values are given, otherwise specifies the left edge as the origin for the next offset.
center: Computes to 50% (left 50%) for the horizontal position if the horizontal position is not otherwise specified, or 50% (top 50%) for the vertical position if it is.

Positive values represent an offset inward from the edge of the background positioning area. Negative values represent an offset outward from the edge of the background positioning area.

Here are various combinations of the above values with an explanation of how many pixels each one is from the top left corner.

CSS Specifications

The <position> data type is defined in CSS Backgrounds and Borders Module Level 3 (W3C Candidate Recommendation 9 September 2014)
It is also defined in the Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification (W3C Recommendation 07 June 2011)
It is also defined in Cascading Style Sheets, level 1 (W3C Recommendation 17 Dec 1996)