Title: CSS Easing Functions Level 2
Status: ED
Work Status: exploring
Shortname: css-easing
Level: 2
Group: csswg
ED: https://drafts.csswg.org/css-easing/
TR: https://www.w3.org/TR/css-easing-2/
Editor: Jake Archibald, Google, jakearchibald@google.com, w3cid 76394
Editor: Brian Birtles, Mozilla https://www.mozilla.org/, bbirtles@mozilla.com, w3cid 43194
Editor: Dean Jackson, Apple Inc https://www.apple.com/, dino@apple.com, w3cid 42080
Editor: Matt Rakow, Microsoft, w3cid 62267
Former Editor: Shane Stephens, Google, shans@google.com, w3cid 47691
Markup Shorthands: markdown yes
Indent: 2
Abstract: This CSS module describes a way for authors to define a transformation
that controls the rate of change of some value.
Applied to animations, such transformations can be used to produce
animations that mimic physical phenomena such as momentum or to cause the
animation to move in discrete steps producing robot-like movement.
Level 2 adds more sophisticated functions for custom easing curves.
!Participate: IRC: #css on W3C's IRC
Repository: w3c/csswg-drafts
{
"FUND-COMP-GRAPHICS": {
"title": "Fundamentals of Computer Graphics",
"authors": [
"Peter Shirley",
"Michael Ashikhmin",
"Steve Marschner"
],
"date": "2009",
"publisher": "A K Peters Limited"
}
}
Introduction {#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.
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.
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 [-∞, ∞].
Some types of easing functions also take an additional boolean [=before flag=]
input which is defined subsequently.
This specification defines four types of easing functions whose definitions
follow.
The syntax for specifying an [=easing function=] is as follows:
<easing-function> =
''linear'' |
<> |
<> |
<>
## The linear easing function: ''linear()'' ## {#the-linear-easing-function}
A linear easing function
is an [=easing function=]
that interpolates linearly
between its [=linear easing function/points=].
A [=linear easing function=] has points,
a [=/list=] of [=linear easing points=].
Initially a new empty [=/list=].
A linear easing point
is a [=/struct=]
that has:
: input
:: A number or null
Note: This is only null during [=create a linear easing function=].
: output
:: A number
### Syntax ### {#linear-easing-function-syntax}
A [=linear easing function=] has the following syntax:
''linear()'' is parsed into a [=linear easing function=]
by calling [=create a linear easing function=],
passing in its <> as a [=/list=] of <>s.
### Parsing ### {#linear-easing-function-parsing}
To create a linear easing function
given a [=/list=] of <>s |stopList|,
perform the following.
It returns a [=linear easing function=] or failure.
1. Let |function| be a new [=linear easing function=].
1. Let |largestInput| be negative infinity.
1. If there are less than two [=list/items=] in |stopList|, then return failure.
1. [=list/For each=] |stop| in |stopList|:
1. Let |point| be a new [=linear easing point=]
with its [=linear easing point/output=] set to |stop|'s <> as a number.
1. [=list/Append=] |point| to |function|'s [=linear easing function/points=].
1. If |stop| has a <>, then:
1. Set |point|'s [=linear easing point/input=] to whichever is greater:
|stop|'s <>'s first <> as a number,
or |largestInput|.
1. Set |largestInput| to |point|'s [=linear easing point/input=].
1. If |stop|'s <> has a second <>, then:
1. Let |extraPoint| be a new [=linear easing point=]
with its [=linear easing point/output=] set to |stop|'s <> as a number.
1. [=list/Append=] |extraPoint| to |function|'s [=linear easing function/points=].
1. Set |extraPoint|'s [=linear easing point/input=] to whichever is greater:
|stop|'s <>'s second <> as a number,
or |largestInput|.
1. Set |largestInput| to |extraPoint|'s [=linear easing point/input=].
1. Otherwise, if |stop| is the first [=list/item=] in |stopList|, then:
1. Set |point|'s [=linear easing point/input=] to 0.
1. Set |largestInput| to 0.
1. Otherwise, if |stop| is the last [=list/item=] in |stopList|,
then set |point|'s [=linear easing point/input=] to whichever is greater:
1 or |largestInput|.
1. For runs of [=list/items=] in |function|'s [=linear easing function/points=] that have a null [=linear easing point/input=],
assign a number to the [=linear easing point/input=] by linearly interpolating between the closest previous and next [=linear easing function/points=]
that have a non-null [=linear easing point/input=].
1. Return |function|.
### Serializing ### {#linear-easing-function-serializing}
The serialization of ''linear()'' includes input values for each point,
and input values are never less than the input of the previous point.
For example:
- ''linear(0, 0.25, 1)'' serializes as ''linear(0 0%, 0.25 50%, 1 100%)''
- ''linear(0 20%, 0.5 10%, 1)'' serializes as ''linear(0 20%, 0.5 20%, 1 100%)''
- ''linear(0, 0.25 25% 75%, 1)'' serializes as ''linear(0 0%, 0.25 25%, 0.25 75%, 1 100%)''
To get a [=linear easing function=]'s (|linearEasingFunction|) serialized computed value,
perform the following.
It returns a [=string=].
1. Let |output| be "`linear(`".
1. [=list/For each=] |point| in |linearEasingFunction|'s [=linear easing function/points=]:
1. If |point| is not the first [=list/item=] of |linearEasingFunction|'s [=linear easing function/points=],
append ", " to |output|.
1. Append the computed value of |point|'s [=linear easing point/output=],
as a <>,
to |output|.
1. Append "" to |output|.
1. Append the computed value of |point|'s [=linear easing point/input=],
as a <>,
to |output|.
1. Append "`)`" to |output|.
1. Return |output|.
### Output of a linear easing function ### {#linear-easing-function-output}
To calculate linear easing output progress
for a given [=linear easing function=] |linearEasingFunction|,
and an [=input progress value=] |inputProgress|,
perform the following.
It returns an [=output progress value=].
1. Let |points| be |linearEasingFunction|'s [=linear easing function/points=].
1. Let |pointAIndex| be index of the last [=list/item=] in |points|
with an [=linear easing point/input=] less than or equal to |inputProgress|,
or 0 if there is no match.
1. If |pointAIndex| is equal to |points| [=list/size=] minus 1,
decrement |pointAIndex| by 1.
Note: This ensures we have a "next" [=linear easing point|point=] to compare to.
1. Let |pointA| be |points|[pointAIndex].
1. Let |pointB| be |points|[pointAIndex + 1].
1. If |pointA|'s [=linear easing point/input=] is equal to |pointB|'s [=linear easing point/input=],
return |pointB|'s [=linear easing point/output=].
1. Let |progressFromPointA| be |inputProgress| minus |pointA|'s [=linear easing point/input=].
1. Let |pointInputRange| be |pointB|'s [=linear easing point/input=] minus |pointA|'s [=linear easing point/input=].
1. Let |progressBetweenPoints| be |progressFromPointA| divided by |pointInputRange|.
1. Let |pointOutputRange| be |pointB|'s [=linear easing point/output=] minus |pointA|'s [=linear easing point/output=].
1. Let |outputFromLastPoint| be |progressBetweenPoints| multiplied by |pointOutputRange|.
1. Return |pointA|'s [=linear easing point/output=] plus |outputFromLastPoint|.
### Examples ### {#linear-easing-function-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:
By default, values are spread evenly between entries that don't have an explicit "input".
Input values can be provided using a <>.
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'':
If two input values are provided for a single output,
it results in two points with the same output.
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:
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:
```css
: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.
More points could be used to create a smoother result,
which may be needed for slower animations.
The linear easing keyword: ''linear''
The linear keyword
produces a [=linear easing function=]
with two [=linear easing function/points=]:
1. : [=linear easing point/input=]
:: 0
: [=linear easing point/output=]
:: 0
1. : [=linear easing point/input=]
:: 1
: [=linear easing point/output=]
:: 1
Note: This results in an identity function,
meaning that its [=output progress value=] is equal to the
[=input progress value=] for all inputs.
Note: Although this produces a [=linear easing function=],
uses of the keyword ''linear'' always serialize as-is, to ''linear''.
Whereas the function equivalent ''linear(0, 1)'' will serialize to ''linear(0 0%, 1 100%)''.
These rules are in [Serialization](#serialization).
A cubic Bézier easing function is
a type of [=easing function=] defined by four real numbers
that specify the two control points,
P1 and P2, of a cubic Bézier curve whose
end points P0 and P3
are fixed at (0, 0) and (1, 1) respectively.
The x coordinates of P1 and P2
are restricted to the range [0, 1].
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
(using notation from [[!CSS-VALUES-3]]):
: ease
:: Equivalent to ''cubic-bezier(0.25, 0.1, 0.25, 1)''.
: ease-in
:: Equivalent to ''cubic-bezier(0.42, 0, 1, 1)''.
: ease-out
:: Equivalent to ''cubic-bezier(0, 0, 0.58, 1)''.
: ease-in-out
:: Equivalent to ''cubic-bezier(0.42, 0, 0.58, 1)''.
:
cubic-bezier(<>, <>, <>, <>)
:: Specifies a cubic Bézier easing function.
The four numbers specify points P1 and P2 of
the curve as (x1, y1, x2, y2).
Both x values must be in the range [0, 1] or the definition is
invalid.
The keyword values listed above are illustrated below.
The easing functions produced by each of the cubic Bézier easing
function keyword values.
### Output of a cubic bézier easing function ### {#cubic-bezier-algo}
The mapping from input progress to output progress is performed by
determining the corresponding y value ([=output progress value=]) for
a given x value ([=input progress value=]).
The evaluation of this curve is covered in many sources such as
[[FUND-COMP-GRAPHICS]].
For [=input progress values=] outside the range [0, 1], the curve is extended
infinitely using tangent of the curve at the closest endpoint as follows:
* For [=input progress values=] less than zero,
1. If the x value of P1 is greater than zero, use
a straight line that passes through P1 and P0 as the tangent.
1. Otherwise, if the x value of P2 is greater than
zero, use a straight line that passes through P2 and P0 as the tangent.
1. Otherwise, let the [=output progress value=] be zero for all
[=input progress values=] in the range [-∞, 0).
* For [=input progress values=] greater than one,
1. If the x value of P2 is less than one, use
a straight line that passes through P2 and P3 as the tangent.
1. Otherwise, if the x value of P1 is less than
one, use a straight line that passes through P1 and P3 as the tangent.
1. Otherwise, let the [=output progress value=] be one for all
[=input progress values=] in the range (1, ∞].
A step easing function is a type of [=easing function=]
that divides the input time into a specified number of intervals that
are equal in length.
It is defined by a number of steps, and a step position.
It has following syntax:
: step-start
:: Computes to ''steps(1, start)''
: step-end
:: Computes to ''steps(1, end)''
Example step easing function keyword values.
: steps(<integer>[, <step-position> ]?)
:: The first parameter specifies the number of intervals in the function.
It must be a positive integer greater than 0
unless the second parameter is jump-none
in which case it must be a positive integer greater than 1.
The second parameter, which is optional, specifies the [=step position=]
using one of the following values:
: jump-start
:: The first rise occurs at [=input progress value=] of 0.
: jump-end
:: The last rise occurs at [=input progress value=] of 1.
: jump-none
:: All rises occur within the range (0, 1).
: jump-both
:: The first rise occurs at [=input progress value=] of 0
and the last rise occurs at [=input progress value=] of 1.
: start
:: Behaves as jump-start.
: end
:: Behaves as jump-end.
If the second parameter is omitted, the value ''end'' is assumed.
These values are illustrated below:
Example step easing functions.
Output of
a step easing function
At the exact point where a step occurs, the result of the function is
conceptually the top of the step. However, an additional before flag
passed as input to the [=step easing function=], if true, will cause the
result of the function to correspond to the bottom of the step at the step
point.
As an example of how the [=before flag=] affects the behavior of this function,
consider an animation with a [=step easing function=] whose [=step
position=] is start and which has a positive
delay and backwards fill.
For example, using CSS animation:
animation: moveRight 5s 1s steps(5, start);
During the delay phase, the [=input progress value=] will be zero but if the
[=before flag=] is set to indicate that the animation has yet to reach its
animation interval, the easing function will produce zero as its [=output
progress value=], i.e. the bottom of the first step.
At the exact moment when the animation interval begins, the [=input progress
value=] will still be zero, but the [=before flag=] will not be set and hence
the result of the easing function will correspond to the top of the first step.
For the purposes of calculating the [=output progress value=], the
[=step position=] start is considered equivalent to
jump-start.
Likewise end is considered equivalent to jump-end.
As a result, the following algorithm does not make explicit reference to
start or end.
Note: User agents must still differentiate between
jump-start and start for
the purpose of serialization (see [[#serialization]]).
The [=output progress value=] is calculated from the [=input progress value=]
and [=before flag=] as follows:
1. Calculate the current step as
floor([=input progress value=] × [=steps=]).
1. If the [=step position=] property is one of:
* jump-start,
* jump-both,
increment current step by one.
1. If both of the following conditions are true:
* the [=before flag=] is set, and
* [=input progress value=] × [=steps=] mod 1 equals zero
(that is, if [=input progress value=] × [=steps=] is
integral), then
decrement current step by one.
1. If [=input progress value=] ≥ 0 and current step < 0,
let current step be zero.
1. Calculate |jumps| based on the [=step position=] as follows:
: jump-start or
jump-end
:: [=steps=]
: jump-none
:: [=steps=] - 1
: jump-both
:: [=steps=] + 1
1. If [=input progress value=] ≤ 1 and current step >
|jumps|, let current step be |jumps|.
Steps 4 and 6 in this procedure ensure that given an [=input progress
value=] in the range [0, 1], a step easing function does not produce an
[=output progress value=] outside that range.
For example, although mathematically we might expect that a step easing
function with a [=step position=] of jump-start
would step up (i.e. beyond 1) when the [=input progress value=] is 1,
intuitively,
when we apply such an easing function to a forwards-filling animation,
we expect it to produce an [=output progress value=] of 1
as the animation fills forwards.
A similar situation arises for a step easing function with
a [=step position=] of jump-end
when applied to an animation during its delay phase.
1. The [=output progress value=] is current step /
|jumps|.
Serialization
Easing functions are serialized using the common serialization patterns
defined in [[CSSOM]] with the following additional requirements:
* The keyword values ''ease'', ''linear'', ''ease-in'', ''ease-out'',
and ''ease-in-out'' are serialized as-is, that is, they are
not converted to the equivalent ''cubic-bezier()'' or
''linear()'' function before serializing.
* Step easing functions, whether they are specified using the
''steps()'' function or either of the ''step-start'' or ''step-end''
keywords, are serialized as follows:
1. If the [=step position=] is ''jump-end'' or ''end'', serialize
as steps(<integer>).
2. Otherwise, serialize as steps(<integer>, <step-position>).
* A [=linear easing function=] created via ''linear()''
is serialized by getting its [=linear easing function/serialized computed value=].
Privacy and Security Considerations {#priv-sec}
===================================
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.
As a result, it does not introduce any new privacy and security concerns.
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.
Changes {#changes}
=======
Additions Since Level 1
- Added ''linear()'' function.
Acknowledgements {#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.
