FAQ

[julianshapiro]

Bug reporting

Unless you're reporting an obvious bug that can be immediately recreated by anyone, please create a demo with the minimum amount of code needed to reproduce your bug. You can use this template, which already has Velocity and the UI pack loaded: http://jsfiddle.net/65xCP/4/.

Using Velocity without jQuery? Here's how you can save a couple KB

If you're using jQuery with Velocity, simply cut out the jQuery shim code at the top of velocity.js. It's simple and safe to do. Just delete all the code that comes before this:

/******************
    Velocity.js
******************/

I don't plan on releasing a build that automatically excises the shim because I don't want to overwhelm users with build options, nor do I want to maintain an additional file.

Disabling transitions during Velocity animation

Velocity automatically adds a velocity-animating class to elements that are in the process of animating. So, you can add a custom class in your stylesheet to disable transitions during these moments, e.g.

.velocity-animating { transition: none }

Velocity is not working on elements cloned within jQuery

Velocity cannot animate elements that have been cloned within jQuery when jQuery's clone function is passed the true argument, which indicates that a deep clone should be performed. This is a result of Velocity relying on jQuery's internal data store when jQuery is present on the page. The act of cloning duplicates an element's data store, which then presents Velocity with stale data values on the cloned element. The solution is to call jQuery's .removeData() after deep cloning an element.

$.css()-like transform setting/getting

To set a transform subproperty (e.g. translateX, rotateZ, scale) in the same manner that you'd instantly set a CSS property using jQuery's $.css() function, use Velocity's hook() function: http://VelocityJS.org/#hook. If, in particular, you wish to animate from an arbitrary transform value that wasn't previously set, use forcefeeding: http://velocityjs.org/#forcefeeding. For example:

/* 90 is your target end value. 123 is your forced start value. */
$element.velocity({ rotateZ: [ 90, 123 ] }, 0);

Preventing memory leaks when creating/destroying large numbers of elements

When you're repeatedly removing elements from the DOM, also call jQuery's $element.removeData() on the target elements to clean them of the data Velocity has saved onto them.

Scrolling a textarea

$("textarea").velocity("scroll", { container: $("textarea"), offset: SCROLL_AMOUNT_HERE });

Using Velocity's slideUp/Down functions for nav menus

Let's say you have a nav menu that slides down into view when the user hovers over it. It may seem like a good idea to stop the sliding down animation then start a sliding up animation if the use hovers off the menu midway through a sliding down animation. (If you don't call stop, the subsequent sliding up animation will queue onto the sliding down animation, which takes a long time to play out. Plus, you don't want a bunch of slide animations queueing onto each other if the user hovers back and forth.)

The problem here is that calling Velocity's stop function will firmly set the element's height at whatever its explicit value is at the moment stop is called. If you then attempt to slide this element down again, it'll slide down to this incorrect height value instead of its original height.

The solution to this problem is to not call stop on sliding elements, and instead avoid re-triggering slide animations if the element is already in the process of sliding. You can achieve this by checking for the presence of a velocity-animating class:

$navContainer.on({
    mouseover: function() {
        if (!$nav.hasClass("velocity-animating")) {
            $nav.velocity("slideDown");
        }
    },
    mouseout: function() {
        if (!$nav.hasClass("velocity-animating")) {
            $nav.velocity("slideUp");
        }
    }
});

Overwriting $.animate()

Do not overwrite jQuery's native $.animate() function with $.velocity(). Keep them separate. Velocity does not guarantee 100% API compatibility with jQuery's $.animate(). Even if it did, overwriting third-party functions is widely considered bad practice.

Contributors

Yehonatan Daniv (@ydaniv): Spring physics, promises, issues moderation.
Jens Anders Bakke (@cfenzo): Initial effects porting for the UI Pack.
Jimmy Gaussen (@nmussy): Initial jQuery dependency removal.

[kapilgarg1996]

The limitations of velocity is nowhere mentioned. Shouldn't it be documented that on what platforms can velocity perform and what minimum browser versions it supports..??

[ydaniv]

They are mentioned in docs.

[milanstosic]

Hi, sorry for writing here but I "googled" and couldn't find a solution and decided to ask here.

I'm interested if there is a way to add "regular" jQuery methods (like .addClass('classX'), .removeClass('classX'), .remove() ) to VelocityJS's queue, and run in a sequence later.

I need to animate a snippet that contain a few elements that need to be animated in a row (when one animation finishes, next one starts) but besides just animating I need some other manipulation (basically class overriding) that I plan to achieve by adding/removing css class on some parent element (screencast - http://cl.ly/3y2f1C061F1f).

Same of my use cases require removing some DOM elements after all animations are finished and at this moment I'm using setTimeout() for removal but I'm interested if I can do everything with VelocityJS.

P.S. I'm still a beginner in VelocityJS and it's possible that I don't understand some of its features (like sequences or so).

[ydaniv]

Use the begin/complete options.

[milanstosic]

@ydaniv Thanks for the super-fast answer! I'll totally overlooked those options - I'll check them now.

[Jon-Biz]

Using Velocity without jQuery? Here's how you can save a couple KB

If you're not using jQuery with Velocity, simply cut out the jQuery shim code at the top of velocity.js. It's >simple and safe to do. Just delete all the code that comes before this...

Shouldn't that read, 'If you are using velocity >with< jquery, you can remove the shim code?'

[Rycochet]

As of Velocity v2 this is almost all outdated and no longer relevant. Future FAQ entries will appear in the wiki.

[bradicalone]

I've searched everywhere and changed my code over and over and still the same. Problem leaving browser page after open and closing side navigation with translate transform it gets stuck when coming back to same browser page. Then when I leave the browser page for 5 seconds come back it automatically gets unstuck.