CSS ray() Function

The ray() function allows you to define a straight line path originating from a specific point at a given angle.

The function is a core part of the CSS Motion Path module. While functions like path() allow you to draw complex, curving routes, the ray() function is specifically designed for straight-line trajectories. It is used almost exclusively with the offset-path property to animate an element along a line.

By default, the ray originates from the center of the element's containing block (though this can be changed using the offset-position property). The angle you specify determines the direction the line shoots out towards. For example, 0deg points straight up, 90deg points to the right, 180deg points down, and 270deg points to the left.

Here's a basic example of an element animating along a 135-degree ray. By animating the offset-distance property from 0% to 100%, the element travels along the defined line:

View Output Full Screen Preview

Controlling the Length of the Ray

By default, the ray extends infinitely. However, when animating an element's offset-distance to 100%, the browser needs to know where the "end" of the ray is. You can control this using a size keyword.

The size keywords dictate how far the ray extends based on the edges or corners of the containing box. For example, closest-side (the default) means the ray's length is equal to the distance to the nearest edge. farthest-corner means its length is equal to the distance to the most distant corner.

The "contain" Keyword

Depending on the size keyword and angle you use, your animated element might bleed outside of its container. For example, if you use farthest-corner but point the ray straight to the right (90deg), the path will be longer than the distance to the right edge, causing the element to shoot out of the box. Furthermore, even if it points exactly to a corner, the center of the element lands on the corner, causing half of it to overflow.

To fix this, you can add the contain keyword inside the ray() function. This forces the browser to shorten the path just enough so that the entire element remains strictly inside the container's boundaries.

Here's a side-by-side comparison demonstrating what happens with and without the contain keyword when using farthest-corner:

.ray-box {
    position: relative;
    width: 150px;
    height: 150px;
    background-color: #e9ecef;
    border: 2px solid #343a40;
  }
  
  .ray-box::before {
    content: attr(data-label);
    position: absolute;
    top: -25px;
    left: 0;
    width: 100%;
    text-align: center;
    font-family: sans-serif;
    font-size: 0.85em;
    font-weight: bold;
    white-space: nowrap;
  }

.moving-element {
    width: 40px;
    height: 40px;
    color: white;
    display: flex;
    align-items: center;
    justify-content: center;
    font-family: sans-serif;
    font-size: 0.7em;
    font-weight: bold;
    border-radius: 50%;
    position: absolute;
    top: 50%;
    left: 50%;
    animation: shootRayCompare 2.5s ease-in-out infinite alternate;
  }

/* Without contain: Shoots out of the box */
  .no-contain {
    background-color: #d9534f;
    offset-path: ray(135deg farthest-corner);
  }

/* With contain: Stops at the corner */
  .with-contain {
    background-color: #5cb85c;
    offset-path: ray(135deg farthest-corner contain);
  }

@keyframes shootRayCompare {
    0% {
      offset-distance: 0%;
    }
    100% {
      offset-distance: 100%;
    }
  }
</style>

View Output Full Screen Preview

Official Syntax

The official syntax of the ray() function is as follows:

Where <ray-size> is defined as:

Possible Values

As indicated in the official syntax, the ray() function accepts the following values:

angle

Specifies the direction of the ray. 0deg points up, and positive angles proceed clockwise.

ray-size

An optional keyword that determines the length of the ray segment. Possible values include:

closest-side: The ray ends at the closest edge of the containing block.
closest-corner: The ray ends at the closest corner of the containing block.
farthest-side: The ray ends at the farthest edge of the containing block.
farthest-corner: The ray ends at the farthest corner of the containing block.
sides: The ray ends where it intersects the containing block's boundary.

If omitted, the default is closest-side.

contain

An optional keyword. When present, it reduces the length of the ray so that the animated element never overflows the containing block at the end of the path.

CSS Specifications

The ray() function is defined in Motion Path Module Level 1 (W3C Working Draft)

Browser Support

The following table provided by Caniuse.com shows the level of browser support for this feature.