CSS Easing Functions Level 2

1. Introduction

This section is not normative.

It is often desirable to control the rate at which some value changes. For example, gradually increasing the speed at which an element moves can give the element a sense of weight as it appears to gather momentum. This can be used to produce intuitive user interface elements or convincing cartoon props that behave like their physical counterparts. Alternatively, it is sometimes desirable for animation to move forwards in distinct steps such as a segmented wheel that rotates such that the segments always appear in the same position.

Similarly, controlling the rate of change of gradient interpolation can be used to produce different visual effects such as suggesting a concave or convex surface, or producing a striped effect.

Easing functions provide a means to transform such values by taking an input progress value and producing a corresponding transformed output progress value.

1.1. Value Definitions

This specification uses the value definition syntax from [CSS-VALUES-3]. Value types not defined in this specification are defined in CSS Values & Units [CSS-VALUES-3]. Combination with other CSS modules may expand the definitions of these value types.

2. Easing functions

An easing function takes an input progress value and produces an output progress value.

An easing function must be a pure function meaning that for a given set of inputs, it always produces the same output progress value.

The input progress value is a real number in the range [-∞, ∞]. Typically, the input progress value is in the range [0, 1] but this may not be the case when easing functions are chained together.

The output progress value is a real number in the range [-∞, ∞].

Note: While CSS numbers have a theoretically infinite range (see CSS Values 4 § 5.1 Range Restrictions and Range Definition Notation) UAs will automatically clamp enormous numbers to a reasonable range. If easing functions are used outside of the CSS context, care must be taken to either correctly handle potential infinities (including those produced by merely very large values stored in a floating point number), or clamp the output progress value.

Some types of easing functions also take an additional boolean before flag, which indicates the easing has not yet started, or is going in reverse and is past the finish. (Some easing functions can have multiple possible output progress values for a given input progress value, and generally favor the last one specified; this flag instead causes those easing functions to favor the first specified value before the animation has started.)

This specification defines several types of easing functions:

<easing-function> = <linear-easing-function>
                  | <cubic-bezier-easing-function>
                  | <step-easing-function>

2.1. Linear Easing Functions: linear, linear()

A linear easing function is an easing function that interpolates linearly between its control points. Each control point is a pair of numbers, associating an input progress value to an output progress value.

A linear easing function has the following syntax:

<linear-easing-function> = linear | <linear()>
linear() = linear( [ <number> && <percentage>{0,2} ]# )

linear

Equivalent to linear(0, 1)

linear()

Specifies a linear easing function.

Each comma-separated argument specifies one or two control points, with an input progress value equal to the specified <percentage> (converted to a <number> between 0 and 1), and an output progress value equal to the specified <number>. When the argument has two <percentage>s, it defines two control points in the specified order, one per <percentage>.

If an argument lacks a <percentage>, its input progress value is initially empty, but that is immediately corrected by linear() canonicalization after parsing.

2.1.1. Serializing

The linear keyword is serialized as itself.

2.1.2. Output

2.1.3. Examples

linear() allows the definition of easing functions that interpolate linearly between a set of points.

For example, linear(0, 0.25, 1) produces an easing function that moves linearly from 0, to 0.25, then to 1:

Easing	Example
linear
linear(0, .25, 1)

By default, values are spread evenly between entries that don’t have an explicit "input". Input values can be provided using a <percentage>.

For example, linear(0, 0.25 75%, 1) produces the following easing function, which spends 75% of the time transitioning from 0 to .25, then the last 25% transitioning from .25 to 1:

Easing	Example
linear
linear(0, .25 75%, 1)

If two input values are provided for a single output, it results in two points with the same output, causing the easing to "pause" between the two inputs.

For example, linear(0, 0.25 25% 75%, 1) is equivalent to linear(0, 0.25 25%, 0.25 75%, 1), producing the following easing function:

Easing	Example
linear
linear(0, 0.25 25% 75%, 1)

If the input is outside the range provided, the trajectory of the nearest two points is continued.

For example, here are the implicit values from the previous function:

A typical use of linear() is to provide many points to create the illusion of a curve.

For example, here’s how linear() could be used to create a reusable "bounce" easing function:

:root {
  --bounce: linear(
    /* Start to 1st bounce */
    0, 0.063, 0.25, 0.563, 1 36.4%,
    /* 1st to 2nd bounce */
    0.812, 0.75, 0.813, 1 72.7%,
    /* 2nd to 3rd bounce */
    0.953, 0.938, 0.953, 1 90.9%,
    /* 3rd bounce to end */
    0.984, 1 100% 100%
  );
}

.example {
  animation-timing-function: var(--bounce);
}

The definition ends 1 100% 100% to create two final points, so inputs greater than 1 always output 1.

Easing	Example
linear
linear(...)

More points could be used to create a smoother result, which may be needed for slower animations.

2.2. Cubic Bézier Easing Functions: ease, ease-in, ease-out, ease-in-out, cubic-bezier()

A cubic Bézier easing function is an easing function that interpolates smoothly from 0 to 1 using a cubic polynomial, influenced by two control points that the curve will approach but (usually) not actually reach. (The "endpoints" of the cubic Bézier are fixed at (0,0) and (1,1), respectively.)

A cubic Bézier easing function has the following syntax:

<cubic-bezier-easing-function> =
  ease | ease-in | ease-out | ease-in-out | <cubic-bezier()>

cubic-bezier() = cubic-bezier( [ <number [0,1]>, <number> ]#{2} )

The meaning of each value is as follows:

ease-in

A function that starts slowly and smoothly, then quickly approaches the endpoint with an almost linear curve. Equivalent to cubic-bezier(0.42, 0, 1, 1).

ease-out

A function that starts quickly with an almost linear curve, then slowly and smoothly approaches the endpoint. Equivalent to cubic-bezier(0, 0, 0.58, 1).

ease-in-out

A function that starts and ends slowly and smoothly, quickly traversing the middle part. Equivalent to cubic-bezier(0.42, 0, 0.58, 1).

ease

Similar to ease-in-out, but with a quicker start and a slower finish. Equivalent to cubic-bezier(0.25, 0.1, 0.25, 1).

cubic-bezier( x1, y1, x2, y2 )

Specifies a cubic Bézier easing function. The x1 and y1 arguments specify the first control point, and x2 and y2 arguments specify the second control point.

Both x values must be in the range [0, 1] or the definition is invalid.

Details on cubic Bézier curves

Note that this does not use the input progress value as the "t" value commonly used to parametrize cubic Bézier curves (producing a 2d point as the output), but rather uses it as the "x" value on the graph (producing a y value as the output). This means that only the shape of the curve matters, not the velocity along that curve. For example, cubic-bezier(0, 0, 0, 0) and cubic-bezier(1, 1, 1, 1) produce exactly the same (linear) easing, despite the first’s velocity following a t3 curve, while the second follows a t1/3 curve.

In general, cubic Bézier curves can have loops: places where a single x value is associated with multiple y values. The restriction placed on the control points (that their x values be in the [0,1] range) prevent this, so the resulting easing function is well-defined.

The keyword values listed above are illustrated below.

2.2.1. Serializing

The ease-in, ease-out, ease-in-out, and ease keywords serialize as themselves.

2.2.2. Output

2.3. Step Easing Functions: step-start, step-end, steps()

A step easing function is an easing function that divides the input time into a specified number of intervals that are equal in length, and holds the output steady within each of those intervals. It is defined by a number of steps, and a step position. It has the following syntax:

<step-easing-function> = step-start | step-end | <steps()>

steps() = steps( <integer>, <step-position>?)
<step-position> = jump-start | jump-end | jump-none | jump-both
              | start | end

The meaning of each value is as follows:

step-start

Jumps from the starting to the ending value at the start of the easing interval.

Computes to steps(1, start)

step-end

Jumps from the starting to the ending value at the end of the easing interval.

Computes to steps(1, end)

steps( <integer>, <step-position>? )

Divides the input interval into a number of equal steps specified by the <integer>. Within each interval, the output progress value is constant, and is determined according to the <step-position> keyword. If omitted, the <step-position> keyword defaults to end.

If the <step-position> is jump-none, the <integer> must be at least 2, or the function is invalid. Otherwise, the <integer> must be at least 1, or the function is invalid.

The <step-position> keywords are:

jump-start

The first interval has an output progress value of 1/steps, and subsequent intervals rise by 1/steps.

(It "jumps at the start", with no step returning 0.)

jump-end

The first interval has an output progress value of 0, and subsequent intervals rise by 1/steps.

(It "jumps at the end", with no step returning 1.)

jump-none

The first interval has an output progress value of 0, and subsequent intervals rise by 1/(steps-1).

(It "never jumps", with steps returning both 0 and 1.)

jump-both

The first interval has an output progress value of 1/(steps+1), and subsequent intervals rise by 1/(steps+1).

(It "jumps at both ends", with no steps returning 0 or 1.)

start

Behaves as jump-start.

end

Behaves as jump-end.

The jump-* keywords values are illustrated below:

2.3.1. Serializing

Unlike the other easing function keywords, step-start and step-end do not serialize as themselves. Instead, they serialize as "steps(1, start)" and "steps(1)", respectively.

2.3.2. Output

Privacy Considerations

No new privacy considerations have been reported on this specification.

This specification does not directly introduce any new capabilities to the Web platform but rather provides common definitions that may be referenced by other specifications.

Security Considerations

Specifications referencing the features defined in this specification should consider that while easing functions most commonly take an input progress value in the range [0,1] and produce an output progress value in the range [0, 1], this is not always the case. Applications of easing functions should define the behavior for inputs and outputs outside this range to ensure they do not introduce new security considerations.

3. Changes

3.1. Changes since the FPWD of 28 August 2024

3.2. Additions Since Level 1

• Added linear() function.

4. Acknowledgements

This specification is based on the CSS Transitions specification edited by L. David Baron, Dean Jackson, David Hyatt, and Chris Marrin. The editors would also like to thank Douglas Stockwell, Steve Block, Tab Atkins, Rachel Nabors, Martin Pitt, and the Animation at Work slack community for their feedback and contributions.