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.
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:
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-animatingclass to elements that are in the process of animating. So, you can add a custom class in your stylesheet to disabletransitions during these moments, e.g.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
trueargument, 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'shook()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: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
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-animatingclass: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.