npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

xref-js

v0.7.577

Published

`xref` is a lightweight JavaScript library that transforms multi-page applications (MPAs) into smooth, single-page-like experiences. It leverages the power of AJAX and CSS transitions to create seamless page transitions without the complexity of a full si

Downloads

979

Readme

xref({})

xref is a lightweight JavaScript library that transforms multi-page applications (MPAs) into smooth, single-page-like experiences. It leverages the power of AJAX and CSS transitions to create seamless page transitions without the complexity of a full single-page application (SPA) framework.

This package is a Experimental. API is subject to change. The Library works as intended (with bugs) as a npm package or as module inside a app. Inserting the xref.umd.js in eg. a WordPress-App won't work very good right now

In general xref assumes you don not want to update the <head>tag when a page-transition is happening. It only switched the ol body with the new body tag.

Features

  • Easy integration with existing multi-page websites
  • Smooth page transitions with customizable animations
  • Maintains browser history and supports back/forward navigation
  • Lightweight and dependency-free
  • TypeScript support

Install

npm install xref-js
yarn add xref-js
<script src="https://unpkg.com/xref-js@latest/dist/xref.umd.js" defer></script>

Info: Buggy as umd module inside already coded websites

Basic Usage

1. Import

import xref from 'xref-js';

2. Initialize xref with your desired options:

xref({
  debug: true,
  head: {
    update: true, // default: false
    retrigger: {
      css: true, // default: false
      js: true // default: false
    }
  },
  /**
   * `prefetch` can fetch HTML Pages
   * before clicking on them by 
   * setting `prefetch.active` to
   * `true`, `event:'mouseover'` &
   * `delay:0` are default
   */
  prefetch: {
    active: true,
    delay: 0,
    event: 'mouseover',
    media: true,
    js: true,
    css: true
  },
  /**
   * `transition` is the global 
   * Object for transition out and
   * in of pages. 
  */
  transition: {
    /**
     * the DOM Element to swap to the new
     * HTML content to (everything outside
     * stays as on initial page load!)
     */
    swapHtml: 'main',
    /**
     * duration of the main
     * animation in and out!
     * info: duration times of
     * in and out are added.
     * depeding on partial 
     * transtion duration
     * animation is:
     * ________________
     *   [t] of partial out
     * + [t] of swapHtml out
     * + [t] of swapHtml in
     * + [t] of partial in
     * ________________
     * = total time of transition
    */
    duration: 100,
    /**
     * Easing function of the 
     * main page transition
    */
    easing: 'ease',
    /**
     * the transition when the element
     * is inserted in the page
     */
    in: {
      /**
       * translates to CSS Keyframes
       * @keyframe xref-animation-in-[i] {
       *    0%: {
       *      opacity: 0
       *    },
       *    100% {
       *      // if  'to' is set here would be something
       *    }
       * }
      */
      from: {
        opacity: 0,
        filter: 'blur(50px)'
      },
    },
    /**
     * the transition when the element
     * is removed from the page
     */
    out: {
      /**
       * translates to CSS Keyframes
       * @keyframe xref-animation-in-[i] {
       *    0%: {
       *       // if  'from' is set here would be something
       *    },
       *    100% {
       *      opacity: 0
       *    }
       * }
      */
      to: {
        opacity: 0,
        filter: 'blur(50px)'
      }
    },
    callback: {
      onEnter: () => {},
      onStart: () => {},
      onPlay: () => {},
      onPause: () => {},
      onFinish: () => {}
    }
    /** `transition.partials` is an Array of HTMLElements that can be animated 
     * out BEFORE the `transition.swapHtml` Element is animated out 
     * and AFTER the the `transition.swapHtml` Element is animated in.
     */
    partials: [
      {
        element: 'header, footer, aside',
        duration: 100,
        easing: 'ease-in-out',
        in: {
          from: {
            opacity: 0,
          },
        },
        out: {
          to: {
            opacity: 0,
          }
        }
      },
    ]
  }
});

You can have seperate animations for 'in' and 'out' or set either one them, the missing one is assumed the provided played backwards!

You can set 'from' and 'to' optionaly, it would make sense to only do 'from' in the 'in' objecte and do 'to' in the 'out' object.

3. Ensure your HTML links are relative or to the same domain:

<a href="/about">About</a>
<a href="/contact">Contact</a>

xref will automatically intercept clicks on these links and handle the page transitions.

How It Works

xref intercepts clicks on links within your site. Instead of allowing the browser to load a new page, it:

  1. Fetches the new page content via AJAX
  2. Smoothly transitions out the current page content
  3. Updates the browser's history
  4. Swaps in the new page content with a transition effect
  5. Manages the <head> tag to ensure styles and scripts are correctly updated

This creates a fluid, app-like experience while maintaining the structure and SEO benefits of a traditional multi-page site.

Advanced Usage

xref offers several advanced features and customization options:

  • Custom transition effects
  • Control over which HTML element is swapped
  • Handling of external scripts and styles
  • Integration with CSS frameworks like Tailwind CSS

Refer to the full documentation for detailed information on these features.

API & Types

interface XrefOptions: {
  transition?: {
    swapHtml?: string,
    duration?: number,
    easing?: string,
    out?: {
      from?: Record<string?, string | number | boolean>,
      to?: Record<string?, string | number | boolean>,
    },
    in?: {
      from?: Record<string?, string | number | boolean>,
      to?: Record<string?, string | number | boolean>,
    },
    callback?: {
      onEnter?: Function,
      onStart?: Function,
      onPlay?: Function,
      onPause?: Function,
      onFinish?: Function
    },
    state?: {
      started?: boolean,
      playing?: boolean,
      paused?: boolean,
      finished?: boolean,
    },
    partials?: [
        {
          element?: string,
          duration?: number,
          easing?: string,
          out?: {
            from?: Record<string?, string | number | boolean>,
            to?: Record<string?, string | number | boolean>,
          },
          in?: {
            from?: Record<string?, string | number | boolean>,
            to?: Record<string?, string | number | boolean>,
          }
        }
      ]
    }
  },
  prefetch?: {
    active?: boolean,
    event?: string,
    delay?: number,
    media?: boolean,
    css?: boolean,
    js?: boolean 
  },
  head?: {
    update?: boolean,
    retrigger?: {
      css?: boolean,
      js?: boolean,
      include?: RegexPattern | string,
      exclude?: RegexPattern | string,
    },
  }
};

Browser Support

xref works in all modern browsers that support the History API and CSS transitions. For older browsers, it will gracefully fall back to normal page loads.

Issues & future Features

  • bug: page swap should update the page same a hard reload
  • bug: script dont get updated -> a new page inserted should trigger DOM content loaded on a event listeners DOMContentLoaded and load
  • info: works best with a static header, change script in <head> and end of the body doest load scripts correctly