A dead simple & powerful way of adding rich & adaptive animations to your app which is already using Turbolinks™.
// Shows the initialized element
TurbolinksAnimate.appear();
// Hides the initialized element
TurbolinksAnimate.disappear();There are a number of ways in which you can adopt Turbolinks Animate to your needs:
The vital part is choosing an animation to play. Turbolinks Animate utilizes Animate.css to power them. These are the animations which are currently accessible:
Full list of animations
fadeInfadeInUpfadeInDownfadeInRightfadeInLeftfadeInUpBigfadeInDownBigfadeInRightBigfadeInLeftBigfadeOutfadeOutUpfadeOutDownfadeOutRightfadeOutLeftfadeOutUpBigfadeOutDownBigfadeOutRightBigfadeOutLeftBigbounceInbounceInUpbounceInDownbounceInRightbounceInLeftbounceOutbounceOutUpbounceOutDownbounceOutRightbounceOutLeftflipInXflipInYflipOutXflipOutYlightSpeedInlightSpeedOutrotateInrotateInDownLeftrotateInDownRightrotateInUpRightrotateInUpLeftrotateOutrotateOutDownLeftrotateOutDownRightrotateOutUpRightrotateOutUpLeftrollInrollOutzoomInzoomInUpzoomInDownzoomInRightzoomInLeftzoomOutzoomOutUpzoomOutDownzoomOutRightzoomOutLeftslideInUpslideInDownslideInRightslideInLeftslideOutUpslideOutDownslideOutRightslideOutLeft
There are three ways in which you can specify the animation you want to use. To choose a globally used animation pass an option when initializing Turbolinks Animate:
TurbolinksAnimate.init({animation: 'fadeinright'});Note: The option falls back to fadein.
Note: As a global choice you would only want to use appearing animations, as they will get fade out automatically when the current view disappears.
For alternate approaches take a look at inline animations and animations overriding animations.
-
durationCSS value foranimation-duration. Accepts a string. Defaults to0.3s. -
delayMilliseconds after which animation starts. Accepts an integer orfalse. Defaults tofalse. -
reversedDisappearingWhether or not a reversed animation should be used when disappearing. Accepts a boolean. Defaults tofalse. -
breakpointsAn array of breakpoint objects to specify breakpoints used for Per Device-Type animations. Accepts an array. Defaults to:[{ name: 'mobile', width: 500 },{ name: 'tablet', width: 1024 },{ name: 'desktop', width: 1440 }] -
customListenersRestore the behavior of versions < 2 to set custom listeners to runappear()anddisappear()functions. Accepts a boolean. Defaults tofalse.
TurbolinksAnimate.init({animation: 'fadeinright', duration: '1s', delay: 1000});With Turbolinks Animate you are able to set animations based on the links, who got clicked:
<a href="" data-turbolinks-animate-animation="fadeout" data-turbolinks-animate-duration="0.3s" data-turbolinks-animate-delay="250">I am a link!</a>-
data-turbolinks-animate-animationAnimation to be applied when disappearing after a hyperlink got clicked. Accepts a string. Set it to'false'to disable Turbolinks Animate on this specific link. -
data-turbolinks-animate-appearAnimation to be applied when appearing on the next view after a hyperlink got clicked. Accepts a string. -
data-turbolinks-animate-durationCSS value foranimation-duration. Accepts a string. -
data-turbolinks-animate-delayMilliseconds after which animation starts. Accepts an integer orfalse.
In addition you can specify animations specifically for certain screen sizes, just pass a hash:
TurbolinksAnimate.init({animation: {'mobile': 'fadeinup', 'tablet': 'fadeindown', 'desktop': 'fadein'}});Note: You can customize the breakpoints through the options.
A lot of times with frameworks like Ruby on Rails you want to be able to specify animations from within your controllers and views without nasty javascript nesting.
With Turbolinks Animate you can just add a data attribute to your initialized element, naming the animation you want to use. It will override the global default:
<body data-turbolinks-animate-animation="fadeinup"></body>A lot of times you want to persist certain elements throughout requests, for example a navigation bar or other parts of your layout that is being shared between views. Turbolinks Animate makes it dead simple to declare persistent elements in your view:
<body data-turbolinks-animate-animation="fadein">
<h1 data-turbolinks-animate-persist="true">My app</h1>
<p>This is specific to my view!</p>
</body>Note: Elements don't actually persist, the get replaced by the fetched page just like any other element. But because no animation gets applied, they look just as if the persist (as long as the newly fetched page includes the exact same element in the same position).
Setting data-turbolinks-animate-persist to true will result in the entire element (including its children) being excluded from the applied animations. If you want to apply the animations to children of the persistent element, but still keep it untouched, append -itself to the data attribute. This is especially useful, when you apply a background color to your element, which remains the same, but changes it contents:
<body data-turbolinks-animate-animation="fadein">
<nav data-turbolinks-animate-persist-itself="true" style="background: black;">
<h1 style="color: white;">View specific title</h1>
</nav>
<p>This is specific to my view!</p>
</body>Often your permanent elements depend on the hyperlink clicked. Just specify the animation type on the hyperlink tag, and replace true with the chosen type on the persistent element:
<body data-turbolinks-animate-animation="fadein">
<nav data-turbolinks-animate-persist-itself="nav" style="background: black;">
<h1 style="color: white;">View specific title</h1>
</nav>
<a href="/do" data-turbolinks-animate-type="nav">Persist navigation!</a>
<a href="/doo">Don't persist navigation!</a>
</body>In a lot of cases it can be useful to apply custom CSS transitions to specific elements when the page changes. This works especially well with background colors of persisted elements, but can be used for any CSS property on any element. Multiple properties can be transitioned using using comma separated values.
<header data-turbolinks-animate-persist-itself="true" data-turbolinks-animate-transition="background-color,opacity">
<!-- ... -->
</header>header {
transition: 0.25s background-color ease-out;
}
#page1 header {
background-color: blue;
}
#page2 header {
background-color: red;
}When you have a third page, which doesn't contain a header element, the page transition performs normally as this method only applies when Turbolinks Animate can find a matching element on the new page.
Important: Unless you only use this data attribute for elements that can be distinguished by their HTML tag, you have to declare an id.
Turbolinks Animate emits events that allow you to track the animation lifecycle. Turbolinks Animate fires events on the document object.
-
turbolinks:animation-startfires when an animation starts. The main Turbolinks Animate element can be accessed withevent.data.element. Access the animation withevent.data.animation. Access whether content appears or disappears withevent.data.disappearing. -
turbolinks:animation-endfires when an animation ends. The main Turbolinks Animate element can be accessed withevent.data.element. Access whether content appeared or disappeared withevent.data.disappearing.
-
Fork this repository
-
Clone your forked git locally
-
Install dependencies
$ yarn install -
Run ESLint
$ yarn eslint
- Review breaking changes and deprecations in
CHANGELOG.md. - Change the version in
package.json. - Reset
CHANGELOG.md. - Create a pull request to merge the changes into
master. - After the pull request was merged, create a new release listing the breaking changes and commits on
mastersince the last release. - The release workflow will publish the package to NPM and GPR.
We use GitHub projects to coordinate the work on this project.
To propose your ideas, initiate the discussion by adding a new issue.
We hope that you will consider contributing to Turbolinks Animate. Please read this short overview for some information about how to get started:
Learn more about contributing to this repository, Code of Conduct
Turbolinks Animate follows Semantic Versioning 2.0 as defined at http://semver.org.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
![depfu[bot] avatar](https://avatars.githubusercontent.com/in/715?v=4 "depfu[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent