Route Transition

Animate simple static site pages routing.

Use case

Add smooth navigating between multiple static pages without reloading.

DEMO

Install

npm

npm install route-transition

Quick start

Include

import RouteTransition from 'route-transition';

or from cdn

<script src="https://cdn.jsdelivr.net/npm/route-transition"></script>

window.RouteTransition;

Styles (optional, for default behavior):

@import 'route-transition/styles';

or from cdn

<link href="https://cdn.jsdelivr.net/npm/route-transition/packages/library/dist/styles.min.css" rel="stylesheet" />

Usage

1. Add rt-action-link class to navigation links:

<nav>
  <a href="page-1.html" class="rt-action-link"></a>
  <a href="page-2.html" class="rt-action-link"></a>
  <a href="page-3.html" class="rt-action-link"></a>
</nav>

2. Add rt-content id to the main content and rt-el-animation class to the animated elements:

<!-- Page 1 -->
<main id="rt-content"> <!-- main tag just for semantic example -->
  page 1 content
  <div class="rt-el-animation">page 1 element 1</div>
  <div class="rt-el-animation">page 1 element 2</div>
  <div class="rt-el-animation">page 1 element 3</div>
  <div class="rt-el-animation">page 1 element 4</div>
</main>

Similar: Page 2, Page 3, ..., Page N.

The library loads page html and replaces rt-content.

3. Initialize

const rt = new RouteTransition();
rt.run();

Now, when navigating, an animation of hiding and showing page elements will appear without reloading the page.

Usage limitations

• This library can be used for simple static site with common styles for all pages.
• Only one instance of RouteTransition can be created due to the global router popstate listener.
• All listeners attached outside the main content must be detached manually.
• Clicking a link while transition is in progress will have no effect until it completes.

Options

Option	Description	Default
linkSelector	selector for element a with href attribute. Page will be uploaded after click	.rt-action-link
contentSelector	selector for main content (replaced element)	#rt-content
animation	animation options
animation.elSelector	selector for elements to animate	.rt-el-animation
animation.in	options that describe how elements should be animated when new page content is inserted
animation.in.duration	{ min, max } or number	from styles
animation.in.delay	{ min, max } or number	from styles
animation.in.class	added to animate element when new page content is inserted; removed after animation	rt-el-animation-in
animation.in.beforeClass	added to all elements when main content is inserted to the page; removed from particular element when animation started	rt-el-animation-before-in
animation.out	options that describe how elements should be animated while new page content is loading
animation.out.duration	{ min, max } or number	from styles
animation.out.delay	{ min, max } or number	from styles
animation.out.class	added to animate element while new page content is loading; removed after animation	rt-el-animation-out

duration and delay — random time from min to max or determined number; animation/transition-duration/delay will be set.

class — animation element class.

Methods

• run() — attach all required listeners.
• getPhase() — get current animation phase ('in' or 'out').
• setProcess(process?: AnimationProcessOptions) — set process for current animation phase, that defines animation elements order and changes animation settings for particular element.
• destroy() — detach all required listeners.
• on(type: string, subscriber: SubscriberFunction) — attach custom event listener.
• off(type?: string, subscriber?: SubscriberFunction) — detach custom event listener (or all listeners if no arguments are provided).

Events

• action — emits when action link was clicked.

// eventData:
type RouterActionEvent = {
  type: 'link-click' | 'popstate';
  nativeEvent?: Event;
  target?: HTMLElement;
  fromHref: string;
  toHref: string;
};

• load — emits when page with main content was loaded.

// eventData:
type LoadingContent = {
  contentElement: HTMLElement;
  documentTitle: string;
};

• insert — emits when main content was replaced by new one.

// eventData:
type LoadingContent = {
  contentElement: HTMLElement;
  documentTitle: string;
};

• process — emits before animation in or out; order and animation settings for particular element can be set by providing setProcess (example below).

// eventData:
type ProcessEvent = {
  animatedEls: Array<HTMLElement>;
  phase: AnimationPhase;
};

• complete — emits when page was loaded, inserted and all animations were finished.

• error — emits when there was any error. See Errors section below.

  eventData: errorObj.

Errors

import {
  HrefNotFoundError,
  ContentElementNotFoundError,
  // ...
} from 'route-transition';

• ContentElementNotFoundError — there is no element matched specified selector (contentSelector).

interface ContentElementNotFoundError extends Error {
  selector: string;
  phase: AnimationPhase;
}

• HrefNotFoundError — clicked a element matched linkSelector has no href attribute.

interface HrefNotFoundError extends Error {
  element: HTMLElement;
  selector: string;
}

• AnimationError — any animation error.

interface AnimationError extends Error {
  element: HTMLElement;
  animationClass: string;
}

and some specific network errors:

• RequestError

interface RequestError extends Error {
  response: Response;
}

and + all erorrs that throws fetch and response.text().

Advanced usage examples

You can use styles with predefined animations and override default classes or use your own:

.rt-el-animation-out,
.rt-el-animation-in {
  animation: myContentAnimation;
  animation-duration: 0.25s;
  /* ... */

  /* or transitions */
}

Thus you can animate each page in its own way.

const rt = new RouteTransition({
  linkSelector: '.rt-action-link',
  contentSelector: '#rt-content',
  animation: {
    elSelector: '.rt-el-animation',
    in: {
      class: 'rt-el-animation-in',
      beforeClass: 'rt-el-animation-before-in',
      // duration: { min: 50, max: 500 },
      // delay: { min: 50, max: 500 },
    },
    out: {
      class: 'rt-el-animation-out',
      // duration: { min: 50, max: 500 },
      // delay: { min: 50, max: 500 },
    },
  },
});

And then

rt.run();

rt.on('action', (eventData) => {});
rt.on('load', (eventData) => {});
rt.on('insert', (eventData) => {});
rt.on('process', (eventData) => {
  // set order and animation options for particular elements
  rt.setProcess([
    // animate el0
    {
      animation: {
        el: els[0],
        class:
          rt.getPhase() === 'in'
            ? 'my-animation-in'
            : 'my-animation-out',
        duration: { min: 200, max: 2000 },
        delay: { min: 50, max: 300 },
      },
    },
    // then animate el1, el2 together
    {
      all: [
        { el: els[1] },
        { el: els[2] },
      ],
    },
    // and then animate el3
    { animation: { el: els[3] } },
  ]);
});
rt.on('complete', () => {});
rt.on('error', (error) => {});

License

Released under MIT license