Sign in

.style()

Sets an inline style property on all of the selected elements.

May also be used to start an animation.

Syntax

neon.style(string style, string value)
neon.style(string style, string value, string lastval [, Number duration
  [, easing [, function endfunc]]])

style

The property name of the style to set.

value

The value to set the style property to. When animating, this is the initial value to set the style property to.

lastval

When animating, the final value to set the style property to. This value must use the same unit of measurement as value, and (when lastval is present) both values must contain the appropriate unit of measurement even if their value is 0.

duration

The duration for the animation in milliseconds (default: 400).

easing

The easing style for the animation (default: "out"). This may either be one of several strings, or a function.

endfunc

A callback function that will be called when the animation completes.

Requirements

This method should be executed on a selection of elements. Please see the .select() method.

Return value

This method is chainable. It returns a copy of the Neon object on which it was called.

Description

This method can be used to set an inline style property on the selected elements. A single property may be set at a time, though multiple assignments may be chained together:

// Chain multiple styles
neon.select(".gobutton").style("background", "#eee").style("padding", "2px 4px");

Often, it is preferential to use .styleRule() instead, which sets a rule in a stylesheet rather than an inline style. Unlike inline styles, style rules can be overridden by CSS stylesheets, and will apply to all matching elements, including those created in the future. Inline styles, however, are useful when the style is likely to change a lot.

Cross-browser compatibility

Some steps have been taken to improve cross-browser compatibility for style properties:

  • "opacity"

    This style property sets the opacity across all browsers, removing the need to set a separate "filter" property for Microsoft browsers. This property accepts a numeric value between 0 and 1.

  • "float"

    This property should work on all browsers, including those that would otherwise require "cssFloat" or "styleFloat" instead.

Animation

When supplied with a third argument, this method may be used to start an animation.

The simplest animation just starts a property at one value and gradually eases it toward another value:

// Animate a box from 0 to 300px width
neon.select(“#mydiv”).style(“width”, “0px”, “300px”);

Further optional arguments may be used to customise the animation. msec specifies the animation's duration:

// Force the animation to take 3 seconds
neon.select(“#mydiv”).style(“width”, “0px”, “300px”, 3000);

It is safe to have many animations in action at the same time, whether different properties on the same element(s) or different elements. Neon will only use a single timer and animation loop function to process all ongoing animations, ensuring the smoothest achievable performance when multiple animations are in process.

Neon's internal animation timer will try to run as close as possibly to 60 times per second on all browsers, though it will self-adjust in either direction in case this cannot be maintained. Animations will run more coarsely when this rate cannot be reached, but will finish in the same amount of time.

Easing functions

The easing parameter specifies the easing function to be used. This affects the motion of the animation. The available easings are:

  • "lin"

    A linear easing. The animation will travel smoothly from start to end at a constant speed, without a smooth acceleration or deceleration.

  • "in"

    The animation slowly accelerates at the start, gaining speed throughout the animation due to constant acceleration and stops abruptly at the end. This is similar to the effect of gravity.

  • "out" (Default)

    The animation starts instantly at high speed, then decelerates constantly throughout the animation, smoothly slowing down to a stop. This is similar to the effect of flicking a card across a table.

  • "inout"

    The animation has both a smooth acceleration and a smooth deceleration, traveling most quickly at the mid-point. The motion is similar to a single movement of a pendulum from one extreme to the other.

  • "el"

    The animation is elastic. The animation starts instantly at high speed, moving towards its target. It overshoots its target, then is drawn back toward it. It will overshoot the target a small number of times before gently coming to rest at the target. This motion is similar to something being pulled by elastic.

  • A function

    If the easing argument is a function instead of a string, it will be used as a custom easing function. Given a parameter x between 0 and 1 representing the full duration of the animation, the function should return a value indicating the progress of the animation, where 0 is the start point and 1 is the end point. The function should return 0 when its argument is 0, and return 1 when its argument has reached 1, but it is otherwise unrestricted, and is allowed to overshoot both the start and the end point during the animation.

Callback function

The optional endfunc parameter can be used to supply a function to be executed when the animation completes. This function will be executed only once for a single call to .style(), even if the animation was applied to multiple elements.

The endfunc will run in the context of a Neon object containing the animating elements. That is, from within the function, this will refer to a Neon object containing all of the animating elements, excepting any elements whose animation was stopped prior to finishing.

Beginning an animation from its current style value

When starting an animation, it is necessary to specify both the starting value and the ending value. If you would rather start an animation from the element's current value, you will need to calculate this. An example might be:

// Animate from current width to 300px
var element = neon.select('#myelement');
element.style("width", element.getStyle("width") || "0px", "300px");

In the above example, the || "0px" is a sensible fallback in case the current width cannot be determined. It may also be possible to derive the current position of an element from .getPosition().

Stopping an animation before it finishes

To stop an animation, you can use the .style() method with only two parameters in order to assign a static value to the style property.

It is safe to begin a new animation on a property while the property is still being animated. In this case, the first animation will automatically be stopped.

If an animation was happening simultaneously on multiple elements, it is safe to stop some elements from animating while not affecting others. The endfunc, if supplied, will run if any one of the elements animates all the way to the end, but it will not run if all elements were stopped before finishing their animation.