css-animated-properties v1.1.0

CSS Animated Properties

A simple way to list which CSS properties can be animated and how, as defined in various W3C specs.

I needed something like this for a project and hand-rolled some basic data. But it might be useful for other people too, so I pulled out the data, cleaned it up and added some convenience methods.

Enjoy.

Caveats & Citations

Only specs that are Candidate Recommendations or better are counted, with the exception of some Working Drafts that have a lot of traction in browser implementations. So far the WD specs included here are Text Level 3, Flexbox and Transforms.

If a property is not in this list, it's not able to be consistently animated. Technically background-image can be animated in some ways, but against the spec (which says it can’t be animated at all).

For better details about individual browser support, see http://thewebevolved.com/support/animation/properties/. There is also a great amount of detail at http://oli.jp/2010/css-animatable-properties/, but I needed something that was usable by scripts.

Usage

Available on npm as css-animated-properties, or in the browser as a global called cssAnimProps

Properties

animatedProperties

The core data as a simple JS object. Each key is a CSS property. If a property isn’t in the list, it’s not animateable via CSS.

There are convenience methods (listed below) that mean you shouldn’t need to access this list directly, but it’s available for other use cases.

types

The types of values that can be animated. Each key is a value type that is referenced in the animatedProperties list. Each type contains properties of name (display name) and href (link to the W3C spec where the value type is defined).

For quick reference, most of the types are defined at http://www.w3.org/TR/css3-transitions/.

Methods

canAnimate()

• Takes a CSS property and returns whether that property can be animated by CSS.
• Parameters: property (String)
• Returns: Boolean

cssAnimProps.canAnimate('margin');    // true
cssAnimProps.canAnimate('position');  // false

getProperty()

• Takes a CSS property and returns the definition of how it can be animated. For properties that are shorthand combinations of other properties (e.g. border) this definition can be recursive.
• Parameters: property (String), expand (Boolean – optional, default false)
• Returns: Object with a combination of the following properties (all are optional), or null if property can’t be animated.
  • properties (Array) – A list of other CSS properties that make up this property’s definition. The values of the array depend on the expand parameter.
  • types (Array) – A list of one or more types of value – these refer to keys in the types property. Only one of types and properties will be present on the same object.
  • multiple (Boolean) – If true, multiple space-separated values can be present (e.g. transform-origin).
  • repeatable (Boolean) – If true, multiple comma-separated sets of values can be present (e.g. background-position).

cssAnimProps.getProperty('color');
// {name: 'color', types: ['color']}

cssAnimProps.getProperty('position');
// null

cssAnimProps.getProperty('transform-origin');
// {name: 'transform-origin', types: ['length-percentage-calc'], multiple: true}

cssAnimProps.getProperty('border-color');
/*
{
    name: 'border-color',
    properties: [
        'border-top-color',
        'border-right-color',
        'border-bottom-color',
        'border-left-color'
    ]
}
*/

cssAnimProps.getProperty('border-color', true);
/*
{
    name: 'border-color',
    properties: [
        {name: 'border-top-color', types: ['color']},
        {name: 'border-right-color', types: ['color']},
        {name: 'border-bottom-color', types: ['color']},
        {name: 'border-left-color', types: ['color']}
    ]
}
*/

Licence

MIT: http://gilmoreorless.mit-license.org/