Skip to content
Nana UI

Guides

Motion

How Nana UI moves. Duration, easing and distance roles named by intent, shared keyframes, reduced motion that keeps the fade, and optional GSAP and Lenis.

View .md Download

Motion in Nana UI is slow enough to follow and never makes anyone wait. Every component reads the same small set of roles from @nana-tec/ui-motion, so a menu, a toast and a dialog move as one system, in the web components, in React and in Svelte.

npm install @nana-tec/ui-motion

@nana-tec/ui-themes/base already imports the motion stylesheet. If you load the theme, the roles are already on the page.

A component asks for enter or state, never for 420ms. Press Play to compare them side by side, and slow them down to see the shape of each one.

Duration roles
  1. pressPress feedback 120ms
  2. stateHover, focus, selection 200ms
  3. moveIndicators, carets, panels 360ms
  4. enterMenus, popovers, toasts 420ms
  5. exitThe same, leaving 315ms
  6. overlayDialogs, drawers, sheets 520ms
  7. overlayExitOverlays closing 390ms

Closing always takes three quarters of the opening time: whatever arrived gently leaves promptly. Retune a role once and every component follows:

:root {
--nana-motion-enter: 360ms;
--nana-motion-overlay: 600ms;
}

Each curve has one job. Things arriving glide in and settle slowly, things leaving pick up speed as they go, and things that move from rest to rest ease at both ends.

Easing roles
ease-state (0.25, 0.1, 0.25, 1)
ease-enter (0.16, 1, 0.3, 1)
ease-exit (0.32, 0, 0.67, 0)
ease-move (0.65, 0, 0.35, 1)
EasingUsed for
--nana-motion-ease-stateColour, border, shadow and opacity changes
--nana-motion-ease-enterPopovers, menus, toasts, dialogs appearing
--nana-motion-ease-exitThe same, leaving
--nana-motion-ease-moveIndicators, carets, expanding panels, progress

Elements travel a few pixels and settle, without bouncing or overshooting. Click a tile to replay it, change the distance, or turn on reduced motion to see what people who ask for less movement get: the same fade, with no travel.

enter() and exit()

On phones every distance is smaller: 2, 8 and 16 pixels instead of 4, 12 and 24.

Headings come in line by line, rising from behind their own edge. Words suit short paragraphs, where whole lines would feel heavy. Characters are for a single word or a short title, never for body copy.

revealText()

Property work, handled with care from the first viewing to the final key.

Every unit, lease and payment in one calm place, so nothing slips between the cracks.

SplitUse it forAvoid it for
linesHeadlines and hero statementsText that reflows while it plays
wordsShort paragraphs, subtitles, a lead under a titleAnything longer than a few lines
charsOne word or a short titleBody copy, buttons, labels, links

Reveal one heading and the line beneath it, not every paragraph on the page. Body copy that animates as it arrives slows reading down.

OptionValuesDefaultDoes
bylines, words, charslinesWhat each piece is
masktrue, falsetrueRise from behind the line’s own edge, or fade up
triggerload, scrollloadPlay at once, or when the text scrolls into view
stepmilliseconds90 for lines, 35 words, 18 charsThe gap between pieces
delaymilliseconds0Added before the first piece
patternany patternenterThe duration and curve of each piece
threshold0 to 10.2How much must be visible before a scroll reveal plays
rootMarginCSS margin0px 0px -10% 0pxShrinks or grows the area that counts as in view

revealText returns a cleanup that stops every animation and restores the original markup.

splitText does only the splitting, for when you animate the pieces yourself:

import { splitText } from "@nana-tec/ui-motion";
const split = splitText(headline, { by: "words", mask: true });
split.pieces;
split.lines;
split.revert();
ReturnsWhat it is
piecesThe word or character elements, in reading order
linesHow many lines the text sits on
revertPuts the original markup back

Every piece carries --i, its position, and every word carries --line, the line it sits on, so CSS can time a cascade on its own. Words are .nana-split-word, characters .nana-split-char, and masks .nana-split-mask.

Split once and add nana-text-reveal from utilities.css. --nana-text-step sets the gap between pieces:

<h1 class="headline">Property work, handled with care</h1>
<script type="module">
import { splitText } from "@nana-tec/ui-motion";
const headline = document.querySelector(".headline");
splitText(headline, { by: "words" });
headline.classList.add("nana-text-reveal");
</script>
<style>
.headline {
--nana-text-step: 50ms;
}
</style>
  • It still reads as text. Inline markup such as <em> and links stays in place. Split into characters, each word keeps a hidden whole-word copy for screen readers and hides the letters from them, so nothing is spelled out.
  • Lines break where they will finally sit. Splitting waits for web fonts to load, and the markup is restored once the reveal ends, so copy, search and translation work on plain text.
  • Reduced motion never splits. The text fades in as one block, or is simply shown when the reveal was waiting for a scroll. The CSS path falls back to a fade too.
  • Long cascades stay short. However many pieces there are, the whole run finishes within 600ms.

A cascade should read as one gesture. Keep the whole run under about half a second, and use a smaller step as the list grows.

stagger()
  • Unit 4B renewed
  • Payment received
  • Inspection booked
  • Lease drafted
  • Tenant invited
  • Report exported

Dialogs and drawers use the overlay role, the slowest of the set. Closing plays the exit before the native <dialog> closes, including when you press Escape.

Dialog and drawer
Open dialog Open drawer Archive unit 4B? It rises in over 520ms and settles away in 390ms. Press Escape to watch it leave. Cancel Archive

Slides in on the enter curve, out on the exit curve, in three quarters of the time.

The components don’t keep timings of their own. Each one reads a role from the package, and the keyframes come from the same source, so retuning a role retunes every component that uses it.

RoleComponents
pressEvery pressable surface: buttons, icon buttons, interactive cards
stateHover, focus and selected colours everywhere
moveTab indicator, Switch, Radio, Rating, Progress Bar and Ring, Details, Split Panel
enter / exitPopup, Popover, Hover Card, Tooltip, Menu, Menubar, Tab Panel, Toaster
overlay / overlay-exitDialog, Drawer, File Viewer
ambient / spinSkeleton and Carousel shimmer, the loading spinner in Button, Input and Tree

The web components load the keyframes into each shadow root, only when the Nana theme is on. Headless, they don’t animate and nothing waits on an animation. In React and Svelte the same roles reach Tailwind as duration-(--nana-motion-move), ease-enter and animate-rise-in.

For scroll-driven scenes, parallax and timelines, install GSAP and import the gsap entry. It registers Nana’s exact curves with GSAP, so a GSAP tween and a CSS transition on the same page land the same way. Scroll these panels in and out of view.

scrollReveal()
01 Roles Revealed by ScrollTrigger on the enter role.
02 Curves Revealed by ScrollTrigger on the enter role.
03 Entrances Revealed by ScrollTrigger on the enter role.
04 Stagger Revealed by ScrollTrigger on the enter role.

Text works the same way. textReveal splits and reveals on scroll, and with scrub each word lights up as it reaches the middle of the screen and dims again on the way back, so a long statement reads at the pace of the scroll.

textReveal({ scrub: true })

Scroll slowly. Each word lights up as it reaches the middle of the screen, and dims again as you scroll back.

OptionValuesDefaultDoes
bylines, words, charslines, or words with scrubWhat each piece is
masktrue, falsetrue, or false with scrubRise from behind an edge, or fade up
scrubtrue, falsefalseTie each word’s brightness to the scroll
dim0 to 10.18How faint words are before they light up
startScrollTrigger positiontop 85%, or top 80% scrubbedWhen the reveal begins
endScrollTrigger positionbottom 45%Where a scrub finishes
stepmillisecondsas revealTextThe gap between pieces
patternany patternenterThe duration and curve of each piece
scopean elementthe documentLimits selector strings to one part of the page

Under reduced motion textReveal doesn’t split and the text is shown as it is. Keep a scrub to one statement per page, because it asks the reader to scroll at its pace.

Everything is built inside gsap.matchMedia, so it rebuilds when the motion preference changes and returns a cleanup that restores every element.

liquid() moves one indicator between the items of a group. It squashes as it leaves, stretches past the target and settles on the spring ease, so a tab, segment or filter seems to flow into place rather than slide. It watches aria-selected, aria-pressed, aria-checked, aria-current and data-state, so it follows whatever already marks the active item.

liquid()

The indicator only changes its clip-path, never its box, so it can’t overflow a scrolling container. A move that starts mid-flight picks up from where the indicator is. --nana-liquid-radius sets its corners, defaulting to --nana-radius-full. Under reduced motion it jumps straight to the new item.

Lenis eases wheel and touch input toward its target. The sample runs it inside a scroll area. Turn it off to compare with native scrolling.

createSmoothScroll()

01 Roles: wheel and touch input is eased toward its target instead of jumping.

02 Curves: wheel and touch input is eased toward its target instead of jumping.

03 Entrances: wheel and touch input is eased toward its target instead of jumping.

04 Stagger: wheel and touch input is eased toward its target instead of jumping.

05 Overlays: wheel and touch input is eased toward its target instead of jumping.

06 Scroll: wheel and touch input is eased toward its target instead of jumping.

07 Smooth: wheel and touch input is eased toward its target instead of jumping.

08 Roles: wheel and touch input is eased toward its target instead of jumping.

09 Curves: wheel and touch input is eased toward its target instead of jumping.

10 Entrances: wheel and touch input is eased toward its target instead of jumping.

11 Stagger: wheel and touch input is eased toward its target instead of jumping.

12 Overlays: wheel and touch input is eased toward its target instead of jumping.

13 Scroll: wheel and touch input is eased toward its target instead of jumping.

14 Smooth: wheel and touch input is eased toward its target instead of jumping.

Under reduced motion Lenis isn’t created at all, and the browser scrolls natively.

scroll.css holds the rules Lenis expects, smooth native anchor scrolling, and a scroll area with a quiet scrollbar:

@import "@nana-tec/ui-motion/scroll.css";
:root {
--nana-scroll-offset: 4.5rem;
}
Class or variableEffect
--nana-scroll-offsetKeeps anchors and focused targets clear of a sticky header
.nana-scroll-areaContained overscroll, stable gutter, a thin scrollbar
.nana-scroll-fadeFades content in and out at the top and bottom edges
.nana-scroll-snapChildren snap gently into place
--nana-scrollbar-thumb, --nana-scrollbar-trackScrollbar colours

Native smooth scrolling turns itself off under reduced motion and whenever Lenis is running, so the two never fight.

When someone asks for reduced motion, distances become zero and scales become one, but fades stay. A dialog still fades in, so a change on screen is never silent. It just stops moving.