GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing drafts.csswg.org — CSS Easing Functions Module 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.

Example of an easing function that produces an ease-in effect.
Given an input progress of 0.7, the easing function scales the value to produce an output progress of 0.52.
Applying this easing function to an animation would cause it to progress more slowly at first but then gradually progress more quickly.

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.

An example of when easing functions are chained together occurs in Web Animations [WEB-ANIMATIONS] where the output of the easing function specified on an animation effect may become the input to an easing function specified on one of the keyframes of a keyframe effect. In this scenario, the input to the easing function on the keyframe effect may be outside the range [0, 1].

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>

Tests

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 curve used as an easing function. — linear(0, .1 25%, .75 50%, 1)
The shape of the curve follows the control points.
Input progress values serve as `x` values of the curve, whilst the `y` values are the output progress values.

A linear easing function has the following syntax:

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

Tests

linear-timing-functions-syntax.html (live test) (source)

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. This is corrected at used value time by linear() canonicalization.

To canonicalize a linear() function’s control points, perform the following:

If the first control point lacks an input progress value, set its input progress value to 0.
If the last control point lacks an input progress value, set its input progress value to 1.
If any control point has an input progress value that is less than the input progress value of any preceding control point, set its input progress value to the largest input progress value of any preceding control point.
If any control point still lacks an input progress value, then for each contiguous run of such control points, set their input progress values so that they are evenly spaced between the preceding and following control points with input progress values.

After canonicalization, every control point has an input progress value, and the input progress values are monotonically non-decreasing along the list.

Note: Serialization relies on whether or not an input progress value was originally supplied, so that information should be retained in the internal representation. It does not rely on whether a pair of control points were specified as two percentages on a single argument or as separate arguments.

Tests

linear-timing-functions-chrome-406926307-crash.html (live test) (source)

2.1.1. Serializing

The linear keyword is serialized as itself.

To serialize a linear() function:

Let s be the string "linear(".
Serialize each control point of the function, concatenate the results using the separator ", ", and append the result to s.
Append ")" to s, and return it.

To serialize a linear() control point:

Let s be the serialization, as a <number>, of the control point’s output progress value.
If the control point originally lacked an input progress value, return s.
Otherwise, append " " (U+0020 SPACE) to s, then serialize the control point’s input progress value as a <percentage> and append it to s.
Return s.

When serialized, control points originally specified with two input progress values are turned into two separate control points, and the input progress values are in strictly ascending order. For example:

linear(0, 0.25, 1) serializes as linear(0, 0.25, 1)
linear(0 20%, 0.5 10%, 1) serializes as linear(0 20%, 0.5 20%, 1)
linear(0, 0.25 25% 75%, 1) serializes as linear(0, 0.25 25%, 0.25 75%, 1)

2.1.2. Output

To calculate linear easing output progress for a given linear easing function func, an input progress value inputProgress, and an optional before flag (defaulting to false), perform the following. It returns an output progress value.

Let points be func’s control points.
If points holds only a single item, return the output progress value of that item.
If inputProgress matches the input progress value of the first point in points, and the before flag is true, return the first point’s output progress value.
If inputProgress matches the input progress value of at least one point in points, return the output progress value of the last such point.
Otherwise, find two control points in points, A and B, which will be used for interpolation:
1. If inputProgress is smaller than any input progress value in points, let A and B be the first two items in points. If A and B have the same input progress value, return A’s output progress value.
2. Otherwise, if inputProgress is larger than any input progress value in points, let A and B be the last two items in points. If A and B have the same input progress value, return B’s output progress value.
3. Otherwise, let A be the last control point whose input progress value is smaller than inputProgress, and let B be the first control point whose input progress value is larger than inputProgress.
Linearly interpolate (or extrapolate) inputProgress along the line defined by A and B, and return the result.

Tests

linear-timing-functions-output.html (live test) (source)

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)

An example of the above, with a plain linear for contrast.

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:

linear(0, 0.25 75%, 1) plotted on a graph.
The graph has three points.
The first is at 0,0.
The second is at 0.75,0.25.
The third is at 1,1.

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

An example of the above, with a plain linear for contrast.

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:

linear(0, 0.25 75%, 1) plotted on a graph.
The graph has four points.
The first is at 0,0.
The second is at 0.25,0.25.
The third is at 0.75,0.25.
The forth is at 1,1.

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

An example of the above, with a plain linear for contrast.

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:

linear(0, 0.25 75%, 1) plotted on a graph.
The graph has four points.
The first is at 0,0.
The second is at 0.25,0.25.
The third is at 0.75,0.25.
The forth is at 1,1.
The ends of the graph are extended at the angle of the nearest two lines.

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(...)

An example of the above, with a plain linear for contrast.

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 Bezier curve used as an easing function. — A cubic Bézier curve used as an easing function.
The shape of the curve is determined by the location of the control points `P1` and `P2`.
Input progress values serve as `x` values of the curve, whilst the `y` values are the output progress values.

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 t³ curve, while the second follows a t^1/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.

The easing functions produced by keyword values. — The easing functions produced by each of the cubic Bézier easing function keyword values.

Easing	Example
linear
ease-in
ease-out
ease-in-out
ease

The above easing functions in action, each applied to a 3s animation of the circles' left property. A linear easing is provided for contrast.

2.2.1. Serializing

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

To serialize a cubic-bezier() function:

Let s be the string "cubic-bezier(".
Serialize the function’s four arguments as <number>s, concatenate the results using the separator ", ", and append the result to s.
Append ")" to s, and return it.

2.2.2. Output

To calculate cubic Bézier easing output progress for a given cubic Bézier easing function func and an input progress value inputProgress, perform the following. It returns an output progress value.

Let p0 be the point (0,0), p1 be the point given by func’s first two arguments, p2 be the point given by func’s second two arguments, and p3 be the point (1,1).
If inputProgress is within the range [0,1] (inclusive), return the y value corresponding to inputProgress as an x value for the cubic Bézier curve defined as having p0 and p3 as endpoints, and p1 and p2 as control points.

The evaluation of this curve is covered in many sources, such as [FUND-COMP-GRAPHICS].
Otherwise, the curve is extended infinitely, using the tangent of the curve at the endpoints. This tangent is defined as the line between two points, t1 and t2.
- If inputProgress is less than 0, let t1 be p0.
  1. If the x value of p1 is greater than 0, let t2 be p1.
  2. Otherwise, if the x value of p2 is greater than 0, let t2 be p2.
  3. Otherwise, return 0.
- If inputProgress is greater than 1, let t2 be p3.
  1. If the x value of p2 is less than 1, let t1 be p2.
  2. Otherwise, if the x value of p1 is less than 1, let t1 be p1.
  3. Otherwise, return 1.
Return the y value corresponding to inputProgress as an x value for the line passing through t1 and t2.

Tests

cubic-bezier-timing-functions-output.html (live test) (source)

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

Tests

step-timing-functions-syntax.html (live test) (source)

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)

Example step easing keywords. — Example step easing function keyword values.

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:

Easing	Example
linear
steps(3, jump-start)
steps(3, jump-end)
steps(3, jump-none)
steps(3, jump-both)

The above easing functions in action, with a linear provided for comparison. Each steps(3, ...) function divides the animation into three constant periods; they differ only on what the value is within each period.

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.

To serialize a steps() functions:

Let s be the string "steps(".
Serialize the function’s steps, and append it to s.
If the function’s step position is end or jump-end, append ")" to s and return s.
Otherwise, append ", " to s. Serialize the step position as a keyword, and append the result to s. Append ")" to s. Return s.

Tests

timing-functions-syntax-computed.html (live test) (source)

2.3.2. Output

To calculate step easing output progress for a given step easing function func, an input progress value inputProgress, and an optional before flag (defaulting to false), perform the following. It returns an output progress value.

If the before flag is true, return 0.
Let steps be func’s steps, and position be func’s step position.
Divide the interval [-∞, ∞] into several segments, each with an associated value, as follows:
1. [-∞, 0) has the value 0.
2. [1, ∞] has the value 1.
3. [0, 1) is divided into steps half-open intervals, [0, ...) to [..., 1) with their values assigned as defined for the position (see <step-position>).
Note: In other words, at the boundary between intervals, the associated value is the higher value.
Return the associated value for the interval that inputProgress is in.

Tests

step-timing-functions-output.html (live test) (source)

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.

You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.