Convert Figma logo to code with AI

MoOx logopjax

Easily enable fast Ajax navigation on any website (using pushState + xhr)

1,477
124
1,477
39
View on GitHubView on NPM

Top Related Projects

defunkt's avatar

jquery-pjax

16,698

pushState + ajax = pjax

turbolinks's avatar

turbolinks-classic

3,537

Classic version of Turbolinks. Now deprecated in favor of Turbolinks 5.

hotwired's avatar

turbo

7,078

The speed of a single-page web application without having to write any JavaScript

bigskysoftware's avatar

htmx

45,167

</> htmx - high power tools for HTML

livewire's avatar

livewire

23,029

A full-stack framework for Laravel that takes the pain out of building dynamic UIs.

Quick Overview

Pjax is a jQuery plugin that uses AJAX and pushState to deliver a fast browsing experience with real permalinks, page titles, and a working back button. It allows for seamless page transitions without full page reloads, improving the user experience and perceived performance of web applications.

Pros

  • Enhances user experience with smooth, fast page transitions
  • Maintains proper browser history and URL states
  • Reduces server load and bandwidth usage by only fetching necessary content
  • Easy integration with existing jQuery-based projects

Cons

  • Requires JavaScript to be enabled in the browser
  • May not work well with all types of web applications, especially those with complex state management
  • Potential SEO implications if not implemented correctly
  • Depends on jQuery, which may be considered outdated for modern web development

Code Examples

  1. Basic Pjax initialization:
$(document).pjax('a', '#pjax-container');

This code initializes Pjax for all links, loading content into the #pjax-container element.

  1. Pjax with custom options:
$(document).pjax('a', '#pjax-container', {
  fragment: '#pjax-container',
  timeout: 5000,
  scrollTo: false
});

This example sets custom options for Pjax, including the fragment to update, a timeout, and disabling automatic scrolling.

  1. Handling Pjax events:
$(document).on('pjax:start', function() {
  $('#loading').show();
});

$(document).on('pjax:end', function() {
  $('#loading').hide();
});

This code shows how to handle Pjax events, in this case showing and hiding a loading indicator during page transitions.

Getting Started

To get started with Pjax:

  1. Include jQuery and Pjax in your HTML:
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery.pjax/2.0.1/jquery.pjax.min.js"></script>
  1. Initialize Pjax in your JavaScript:
$(document).ready(function() {
  $(document).pjax('a', '#pjax-container');
});
  1. Ensure your server responds with appropriate headers for Pjax requests:
X-PJAX: true
X-PJAX-Container: #pjax-container
  1. Update your server-side code to return only the necessary content for Pjax requests, typically the inner HTML of the #pjax-container.

Competitor Comparisons

defunkt logo

jquery-pjax

16,698

pushState + ajax = pjax

Pros of jquery-pjax

  • Mature and well-established project with a large user base
  • Extensive documentation and community support
  • Seamless integration with jQuery, making it easy to use in existing jQuery projects

Cons of jquery-pjax

  • Dependency on jQuery, which may not be ideal for modern, lightweight web applications
  • Less active development and maintenance compared to pjax
  • Limited compatibility with newer browser features and modern JavaScript practices

Code Comparison

jquery-pjax:

$(document).pjax('a', '#pjax-container')

pjax:

new Pjax({
  elements: "a",
  selectors: ["#pjax-container"]
})

Key Differences

  • pjax is a standalone library without jQuery dependency, making it more lightweight and flexible
  • pjax offers more customization options and better performance in modern browsers
  • jquery-pjax has a simpler API and is easier to implement in jQuery-based projects
  • pjax provides better support for newer web technologies and practices

Conclusion

While jquery-pjax remains a solid choice for jQuery-based projects, pjax offers a more modern, lightweight, and flexible solution for developers looking to implement PJAX functionality in their web applications. The choice between the two largely depends on the project's specific requirements and existing technology stack.

turbolinks logo

turbolinks-classic

3,537

Classic version of Turbolinks. Now deprecated in favor of Turbolinks 5.

Pros of Turbolinks-classic

  • Seamless integration with Ruby on Rails applications
  • Automatic handling of browser history and URL changes
  • Built-in progress bar for loading indication

Cons of Turbolinks-classic

  • Limited customization options compared to Pjax
  • Potential conflicts with JavaScript events and DOM manipulation
  • Less flexibility for partial page updates

Code Comparison

Turbolinks-classic:

// No explicit initialization required
// Turbolinks automatically intercepts link clicks
Turbolinks.visit('/new-page');

Pjax:

// Initialize Pjax
var pjax = new Pjax({
  elements: 'a',
  selectors: ['#main', '#sidebar']
});

// Trigger a Pjax request
pjax.loadUrl('/new-page');

Key Differences

  1. Initialization: Turbolinks-classic works out of the box with minimal setup, while Pjax requires explicit initialization and configuration.

  2. Flexibility: Pjax offers more granular control over which elements to update, allowing for partial page updates. Turbolinks-classic typically replaces the entire <body> content.

  3. Framework integration: Turbolinks-classic is tightly integrated with Ruby on Rails, whereas Pjax is framework-agnostic and can be used with various backend technologies.

  4. Performance: Both libraries aim to improve page load times, but Pjax may offer better performance for partial updates due to its more targeted approach.

  5. Learning curve: Turbolinks-classic has a gentler learning curve for Rails developers, while Pjax requires more understanding of its API and configuration options.

hotwired logo

turbo

7,078

The speed of a single-page web application without having to write any JavaScript

Pros of Turbo

  • More comprehensive framework for building modern web applications
  • Supports multiple page elements updating simultaneously
  • Integrates well with other Hotwire tools like Stimulus

Cons of Turbo

  • Steeper learning curve due to more features and complexity
  • Requires more setup and configuration compared to Pjax
  • May be overkill for simpler projects that only need basic page transitions

Code Comparison

Pjax:

$(document).pjax('a', '#pjax-container')

Turbo:

import { Turbo } from "@hotwired/turbo-rails"
Turbo.start()

Key Differences

  • Turbo is part of the larger Hotwire ecosystem, while Pjax is a standalone library
  • Turbo uses the History API and doesn't rely on jQuery, unlike Pjax
  • Turbo offers more advanced features like lazy loading and form handling

Use Cases

  • Pjax: Ideal for adding simple, jQuery-based AJAX navigation to existing sites
  • Turbo: Better suited for building modern, reactive web applications with rich interactions

Community and Maintenance

  • Pjax: Smaller community, less frequent updates
  • Turbo: Larger community, actively maintained by the Basecamp team
bigskysoftware logo

htmx

45,167

</> htmx - high power tools for HTML

Pros of htmx

  • More comprehensive and feature-rich, offering a wider range of AJAX interactions
  • Supports server-side rendering and progressive enhancement
  • Active development and community support

Cons of htmx

  • Steeper learning curve due to more extensive API and concepts
  • Potentially more complex implementation for simple use cases
  • Larger file size compared to pjax

Code Comparison

htmx:

<button hx-post="/submit" hx-target="#result">
  Submit
</button>
<div id="result"></div>

pjax:

<a href="/page" data-pjax="#main">Load Page</a>
<div id="main"></div>

Key Differences

  • htmx offers a more declarative approach with attributes for various AJAX interactions
  • pjax focuses primarily on page transitions and history management
  • htmx provides more fine-grained control over partial page updates
  • pjax is lighter and may be easier to integrate for simple use cases

Use Cases

  • htmx: Complex web applications with frequent partial updates and interactive elements
  • pjax: Simpler websites or applications primarily focused on smooth page transitions

Community and Maintenance

  • htmx: Active development, regular updates, and growing community support
  • pjax: Less frequent updates, but still maintained and used in various projects
livewire logo

livewire

23,029

A full-stack framework for Laravel that takes the pain out of building dynamic UIs.

Pros of Livewire

  • Full-stack framework with more comprehensive features
  • Seamless integration with Laravel, offering a cohesive development experience
  • Real-time updates without writing JavaScript

Cons of Livewire

  • Steeper learning curve due to its more extensive feature set
  • Heavier payload and potentially slower initial load times
  • Tighter coupling with Laravel, less flexible for other frameworks

Code Comparison

Pjax (JavaScript):

$(document).pjax('a', '#pjax-container')

Livewire (PHP):

class SearchPosts extends Component
{
    public $search = '';

    public function render()
    {
        return view('livewire.search-posts', [
            'posts' => Post::where('title', 'like', "%{$this->search}%")->get(),
        ]);
    }
}

Key Differences

  • Pjax focuses on enhancing navigation with minimal JavaScript
  • Livewire provides a full-stack solution for building dynamic interfaces
  • Pjax is framework-agnostic, while Livewire is tightly integrated with Laravel
  • Livewire offers more advanced features like real-time updates and component-based architecture
  • Pjax has a smaller footprint and may be easier to implement for simple use cases

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Pjax

Build Status.

Easily enable fast AJAX navigation on any website (using pushState() + XHR)

Pjax is a standalone JavaScript module that uses AJAX (XmlHttpRequest) and pushState() to deliver a fast browsing experience.

It allows you to completely transform the user experience of standard websites (server-side generated or static ones) to make users feel like they are browsing an app, especially for those with low bandwidth connections.

No more full page reloads. No more multiple HTTP requests.

Pjax does not rely on other libraries, like jQuery or similar. It is written entirely in vanilla JS.

Installation

  • You can link directly to the bundle:

    <script src="https://cdn.jsdelivr.net/npm/pjax@VERSION/pjax.js"></script>

  • Or the minified bundle:

    <script src="https://cdn.jsdelivr.net/npm/pjax@VERSION/pjax.min.js"></script>

  • You can also install Pjax from npm:

    npm install pjax

    Note: If you use this option, you will need to do one of the following:

    • Link a script tag to either pjax.js or pjax.min.js. E.g.:
    <script src="./node_modules/pjax/pjax.js"></script>
    • Use a bundler like Webpack. (index.js cannot be used in the browser without a bundler).

  • Or you can clone the repo and build the bundle from the source using npm:

    git clone https://github.com/MoOx/pjax.git
cd pjax
npm install
npm run build

    and then link a script tag to either pjax.js or pjax.min.js. E.g.:

    <script src="./pjax.min.js"></script>

What Pjax Does

Under the hood, it's just ONE HTTP request with a pushState() call.

Pjax loads pages using AJAX and updates the browser's current URL using pushState() without reloading your page's layout or any resources (JS, CSS), giving a fast page load.

It works with all permalinks and can update all the parts of the page you want (including HTML metas, title, and navigation state).

In the case of browsers that don't support history.pushState(), Pjax gracefully degrades and does not do anything at all.

Additionally, Pjax:

  • Is not limited to one container, like jQuery-Pjax is.
  • Fully supports browser history (back and forward buttons).
  • Supports keyboard browsing.
  • Automatically falls back to standard navigation for external pages (thanks to Captain Obvious's help).
  • Automatically falls back to standard navigation for internal pages that do not have an appropriate DOM tree.
  • Allows for CSS transitions (animations) very easily.
  • Is only around 6kb (minified and gzipped).

How Pjax Works

  • It listens to every click on links you want (by default all of them).
  • When an internal link is clicked, Pjax fetches the page's HTML via AJAX.
  • Pjax renders the page's DOM tree (without loading any resources - images, CSS, JS, etc).
  • It checks that all defined parts can be replaced:
    • If the page doesn't meet the requirements, standard navigation is used.
    • If the page meets the requirements, Pjax does all defined DOM replacements.
  • Then it updates the browser's current URL using pushState().

Overview

Pjax is fully automatic. You don't need to change anything about your existing HTML, you just need to designate which elements on your page that you want to be replaced when your site is navigated.

Consider the following page.

<!DOCTYPE html>
<html>
<head>
  <!-- metas, title, styles, etc -->
  <title>My Cool Blog</title>
  <meta name="description" content="Welcome to My Cool Blog">
  <link href="/styles.css" rel="stylesheet">
</head>

<body>
  <header class="the-header">
    <nav>
      <a href="/" class="is-active">Home</a>
      <a href="/about">About</a>
      <a href="/contact">Contact</a>
    </nav>
  </header>

  <section class="the-content">
    <h1>My Cool Blog</h1>
    <p>
      Thanks for stopping by!

      <a href="/about">Click Here to find out more about me.</a>
    </p>
  </section>

  <aside class="the-sidebar">
    <h3>Recent Posts</h3>
    <!-- sidebar content -->
  </aside>

  <footer class="the-footer">
    &copy; My Cool Blog
  </footer>

  <script src="onDomReadystuff.js"></script>
  <script>
    // analytics
  </script>
</body>
</html>

We want Pjax to intercept the URL /about, and replace .the-content with the resulting content of the request.

It would also be nice if we could replace the <nav> to show that the /about link is active, as well as update our page meta and the <aside> sidebar.

So all in all we want to update the page title and meta, header, content area, and sidebar, without reloading styles or scripts.

We can easily do this by telling Pjax to listen on all a tags (which is the default) and use CSS selectors defined above (without forgetting minimal meta):

var pjax = new Pjax({
  selectors: [
    "title",
    "meta[name=description]",
    ".the-header",
    ".the-content",
    ".the-sidebar",
  ]
})

Now, when someone in a Pjax-compatible browser clicks an internal link on the page, the content of each of the selectors will be replaced with the specific content pieces found in the next page's content.

Magic! For real! There is no need to do anything server-side!

Differences with jQuery-pjax

  • No jQuery dependency.
  • Not limited to a container.
  • No server-side requirements.
  • Works for CommonJS environment (Webpack/Browserify), AMD (RequireJS) or even globally.
  • Allows page transitions with CSS animations.
  • Can be easily tweaked, since every method is public (and as a result, overridable).

Compatibility

Pjax only works with browsers that support the history.pushState() API. When the API isn't supported, Pjax goes into fallback mode (and it just does nothing).

To see if Pjax is actually supported by your browser, use Pjax.isSupported().

Usage

new Pjax()

Let's talk more about the most basic way to get started.

When instantiating Pjax, you can pass options into the constructor as an object:

var pjax = new Pjax({
  elements: "a", // default is "a[href], form[action]"
  selectors: ["title", ".the-header", ".the-content", ".the-sidebar"]
})

This will enable Pjax on all links, and designate the part to replace using CSS selectors "title", ".the-header", ".the-content", ".the-sidebar".

In some cases, you might want to only target some specific elements to apply Pjax behavior. In that case, you can do two different things:

  1. Use a custom CSS selector( such as "a.js-Pjax" or ".js-Pjax a", etc).
  2. Override Pjax.prototype.getElements.
    • Note: If doing this, make sure to return a NodeList.
// use case 1
var pjax = new Pjax({ elements: "a.js-Pjax" })

// use case 2
Pjax.prototype.getElements = function() {
  return document.getElementsByClassName(".js-Pjax")
}

var pjax = new Pjax()

loadUrl(href, [options])

With this method, you can manually trigger the loading of a URL:

var pjax = new Pjax()

// use case 1
pjax.loadUrl("/your-url")

// use case 2 (with options override)
pjax.loadUrl("/your-other-url", { timeout: 10 })

handleResponse(responseText, request, href, options)

This method takes the raw response, processes the URL, then calls pjax.loadContent() to actually load it into the DOM.

It is passed the following arguments:

  • responseText (string): This is the raw response text. This is equivalent to request.responseText.
  • request (XMLHttpRequest): This is the XHR object.
  • href (string): This is the URL that was passed to loadUrl().
  • options (object): This is an object with the options for this request. The structure basically matches the regular options object, with a few extra internal properties.

You can override this if you want to process the data before, or instead of, it being loaded into the DOM.

For example, if you want to check for a non-HTML response, you could do the following:

var pjax = new Pjax();

pjax._handleResponse = pjax.handleResponse;

pjax.handleResponse = function(responseText, request, href, options) {
  if (request.responseText.match("<html")) {
    pjax._handleResponse(responseText, request, href, options);
  } else {
    // handle non-HTML response here
  }
}

refresh([el])

Use this method to bind Pjax to children of a DOM element that didn't exist when Pjax was initialised e.g. content inserted dynamically by another library or script. If called with no arguments, Pjax will parse the entire document again to look for newly-inserted elements.

// Inside a callback or Promise that runs after new DOM content has been inserted
var newContent = document.querySelector(".new-content");

pjax.refresh(newContent);

reload()

A helper shortcut for window.location.reload(). Used to force a page reload.

pjax.reload()

Options

elements (String, default: "a[href], form[action]")

CSS selector(s) used to find links to apply Pjax to. If needing multiple specific selectors, separate them by a comma.

// Single element
var pjax = new Pjax({
  elements: ".ajax"
})

// Multiple elements
var pjax = new Pjax({
  elements: ".pjax, .ajax",
})

selectors (Array, default: ["title", ".js-Pjax"])

CSS selectors used to find which content to replace.

var pjax = new Pjax({
  selectors: [
    "title",
    "the-content",
  ]
})

If a query returns multiples items, it will just keep the index.

Example of what you can do:

<!DOCTYPE html>
<html>
<head>
  <title>Page title</title>
</head>
<body>
  <header class="js-Pjax">...</header>
  <section class="js-Pjax">...</section>
  <footer class="the-footer">...</footer>
  <script>...</script>
</body>
</html>

This example is correct and should work "as expected".

NOTE: If the current page and new page do not have the same amount of DOM elements, Pjax will fall back to normal page load.

switches (Object, default: {})

This is an object containing callbacks that can be used to switch old elements with new elements.

The object keys should be one of the defined selectors (from the selectors option).

Examples:

var pjax = new Pjax({
  selectors: ["title", ".Navbar", ".js-Pjax"],
  switches: {
    "title": Pjax.switches.outerHTML, // default behavior
    ".the-content": function(oldEl, newEl, options) {
      // this is identical to the default behavior
      oldEl.outerHTML = newEl.outerHTML
      this.onSwitch()
    },
    ".js-Pjax": Pjax.switches.sideBySide
  }
})

Callbacks are bound to the Pjax instance itself to allow you to reuse it (ex: this.onSwitch())

Existing Switch Callbacks

  • Pjax.switches.outerHTML: The default behavior, replaces elements using outerHTML.
  • Pjax.switches.innerHTML: Replaces elements using innerHTML and copies className.
  • Pjax.switches.replaceNode: Replaces elements using replaceChild
  • Pjax.switches.sideBySide: Smart replacing that allows you to have both elements in the same parent when you want to use CSS animations. Old elements are removed when all children have been fully animated (an animationEnd event is triggered).

Creating a Switch Callback

Your callback function can do whatever you want, but you need to:

  1. Replace the oldEl's content with the newEl's content in some fashion.
  2. Call this.onSwitch() to trigger the attached callback.

Here is the default behavior as an example:

function(oldEl, newEl, pjaxOptions) {
  oldEl.outerHTML = newEl.outerHTML
  this.onSwitch()
}

switchesOptions (Object, default: {})

These are options that can be used during content replacement by switches. For now, only Pjax.switches.sideBySide uses it. This is very convenient when you use something like Animate.css with or without WOW.js.

var pjax = new Pjax({
  selectors: ["title", ".js-Pjax"],
  switches: {
    ".js-Pjax": Pjax.switches.sideBySide
  },
  switchesOptions: {
    ".js-Pjax": {
      classNames: {
        // class added to the old element being replaced, e.g. a fade out
        remove: "Animated Animated--reverse Animate--fast Animate--noDelay",
        // class added to the new element that is replacing the old one, e.g. a fade in
        add: "Animated",
        // class added on the element when navigating back
        backward: "Animate--slideInRight",
        // class added on the element when navigating forward (used for new page too)
        forward: "Animate--slideInLeft"
      },
      callbacks: {
        // to make a nice transition with 2 pages at the same time
        // we are playing with absolute positioning for the element we are removing
        // & we need live metrics to have something great
        // see associated CSS below
        removeElement: function(el) {
          el.style.marginLeft = "-" + (el.getBoundingClientRect().width/2) + "px"
        }
      }
    }
  }
})

Note that remove includes Animated--reverse which is a simple way to not have to have a duplicate transition (slideIn + reverse => slideOut).

Here is some css that works well with the above configuration:

/*
  Note: If your content elements don't have a fixed width it can cause
  an issue when positioning absolutely
*/
.js-Pjax { position: relative } /* parent element where switch will be made */

.js-Pjax-child { width: 100% }

/* position for the elements that will be removed */
.js-Pjax-remove {
  position: absolute;
  left: 50%;
  /* transform: translateX(-50%) */
  /* transform can't be used since we already use generic translate for the remove effect (eg animate.css) */
  /* margin-left: -width/2; // made with js */
  /* you can totally drop the margin-left thing from switchesOptions if you use custom animations */
}

/* CSS animations */
.Animated {
  animation-fill-mode: both;
  animation-duration: 1s;
}

.Animated--reverse { animation-direction: reverse }

.Animate--fast { animation-duration: .5s }
.Animate--noDelay { animation-delay: 0s !important;  }

.Animate--slideInRight { animation-name: Animation-slideInRight }

@keyframes Animation-slideInRight {
  0% {
    opacity: 0;
    transform: translateX(100rem);
  }

  100% {
    transform: translateX(0);
  }
}

.Animate--slideInLeft { animation-name: Animation-slideInLeft }

@keyframes Animation-slideInLeft {
  0% {
    opacity: 0;
    transform: translateX(-100rem);
  }

  100% {
    transform: translateX(0);
  }
}

To give context to this CSS, here is an HTML snippet:

<!doctype html>
<html>
<head>
  <title>Page Title</title>
</head>
<body>
  <section class="js-Pjax">
    <div class="js-Pjax-child">
      Your content here
    </div>
    <!--
    During the replacement process, you'll have the following tree:

    <div class="js-Pjax-child js-Pjax-remove Animate...">
      Your OLD content here
    </div>
    <div class="js-Pjax-child js-Pjax-add Animate...">
      Your NEW content here
    </div>

    -->
  </section>
  <script>...</script>
</body>
</html>

history (Boolean, default: true)

Enable the use of pushState(). Disabling this will prevent Pjax from updating browser history. While possible, there is almost no use case where you would want to do this.

Internally, this option is used when a popstate event triggers Pjax (to not pushState() again).

analytics (Function | Boolean, default: a function that pushes _gaq _trackPageview or sends ga pageview

Function that allows you to add behavior for analytics. By default it tries to track a pageview with Google Analytics (if it exists on the page). It's called every time a page is switched, even for history navigation.

Set to false to disable this behavior.

scrollTo (Integer | [Integer, Integer] | False, default: 0)

When set to an integer, this is the value (in px from the top of the page) to scroll to when a page is switched.

When set to an array of 2 integers ([x, y]), this is the value to scroll both horizontally and vertically.

Set this to false to disable scrolling, which will mean the page will stay in that same position it was before loading the new elements.

scrollRestoration (Boolean, default: true)

When set to true, Pjax will attempt to restore the scroll position when navigating backwards or forwards.

cacheBust (Boolean, default: true)

When set to true, Pjax appends a timestamp query string segment to the requested URL in order to skip the browser cache.

debug (Boolean, default: false)

Enables verbose mode. Useful to debug page layout differences.

currentUrlFullReload (Boolean, default: false)

When set to true, clicking on a link that points to the current URL will trigger a full page reload.

When set to false, clicking on such a link will cause Pjax to load the current page without a full page reload. If you want to add some custom behavior, add a click listener to the link and call preventDefault(). This will prevent Pjax from receiving the event.

Note: This must be done before Pjax is instantiated, otherwise Pjax's event handler will be called first, and preventDefault() won't have been called yet.

Here is some sample code:

  var links = document.querySelectorAll(".js-Pjax");

  for (var i = 0; i < links.length; i++) {
    var el = links[i]

    el.addEventListener("click", function(e) {
      if (el.href === window.location.href.split("#")[0]) {
        e.preventDefault();

        console.log("Link to current page clicked");
        // Custom code goes here.
      }
    })
  }

  var pjax = new Pjax()

(Note that if cacheBust is set to true, the code that checks if the href is the same as the current page's URL will not work, due to the query string appended to force a cache bust).

timeout (Integer, default: 0)

The timeout in milliseconds for the XHR requests. Set to 0 to disable the timeout.

Events

Pjax fires a number of events regardless of how it's invoked.

All events are fired from the document, not the link that was clicked.

  • pjax:send - Fired after the Pjax request begins.
  • pjax:complete - Fired after the Pjax request finishes.
  • pjax:success - Fired after the Pjax request succeeds.
  • pjax:error - Fired after the Pjax request fails. The request object will be passed along as event.options.request.

send and complete are a good pair of events to use if you are implementing a loading indicator (eg: topbar)

document.addEventListener('pjax:send', topbar.show)
document.addEventListener('pjax:complete', topbar.hide)

HTTP Headers

Pjax uses several custom headers when it makes and receives HTTP requests. If the requests are going to your server, you can use those headers for some meta information about the response.

Request Headers

Pjax sends the following headers with every request:

  • X-Requested-With: "XMLHttpRequest"
  • X-PJAX: "true"
  • X-PJAX-Selectors: A serialized JSON array of selectors, taken from options.selectors. You can use this to send back only the elements that Pjax will use to switch, instead of sending the whole page. Note that you'll need to deserialize this on the server (Such as by using JSON.parse())

Response Headers

Pjax looks for the following headers on the response:

  • X-PJAX-URL or X-XHR-Redirected-To

Pjax first checks the responseURL property on the XHR object to see if the request was redirected by the server. Most browsers support this, but not all. To ensure Pjax will be able to tell when the request is redirected, you can include one of these headers with the response, set to the final URL.

DOM Ready State

Most of the time, you will have code related to the current DOM that you only execute when the DOM is ready.

Since Pjax doesn't automatically re-execute your previous code each time you load a page, you'll need to add code to re-trigger the DOM ready code. Here's a simple example:

function whenDOMReady() {
  // do your stuff
}

whenDOMReady()

var pjax = new Pjax()

document.addEventListener("pjax:success", whenDOMReady)

Note: Don't create the Pjax instance in the whenDOMReady function.

If you want to just update a specific part (which is a good idea), you can add the DOM-related code in a function and re-execute this function when the pjax:success event is fired.

// do your global stuff
//... DOM ready code

function whenContainerReady() {
  // do your container related stuff
}

whenContainerReady()

var pjax = new Pjax()

document.addEventListener("pjax:success", whenContainerReady)

FAQ

Q: Disqus doesn't work anymore, how can I fix that ?

A: There are a few things you need to do:

  • Wrap your Disqus snippet into a DOM element that you will add to the selector property (or just wrap it with class="js-Pjax") and be sure to have at least an empty wrapper on each page (to avoid differences of DOM between pages).

  • Edit your Disqus snippet like the one below.

Disqus snippet before Pjax integration

<script>
  var disqus_shortname = 'YOURSHORTNAME'
  var disqus_identifier = 'PAGEID'
  var disqus_url = 'PAGEURL'
  var disqus_script = 'embed.js'

  (function(d,s) {
  s = d.createElement('script');s.async=1;s.src = '//' + disqus_shortname + '.disqus.com/'+disqus_script;
  (d.getElementsByTagName('head')[0]).appendChild(s);
  })(document)
</script>

Disqus snippet after Pjax integration

<div class="js-Pjax"><!-- needs to be here on every Pjax-ified page, even if empty -->
<!-- if (some condition) { // eventual server-side test to know whether or not you include this script -->
  <script>
    var disqus_shortname = 'YOURSHORTNAME'
    var disqus_identifier = 'PAGEID'
    var disqus_url = 'PAGEURL'
    var disqus_script = 'embed.js'

    // here we will only load the disqus <script> if not already loaded
    if (!window.DISQUS) {
      (function(d,s) {
      s = d.createElement('script');s.async=1;s.src = '//' + disqus_shortname + '.disqus.com/'+disqus_script;
      (d.getElementsByTagName('head')[0]).appendChild(s);
      })(document)
    }
    // if disqus <script> is already loaded, we just reset disqus the right way
    // see https://help.disqus.com/developer/using-disqus-on-ajax-sites
    else {
      DISQUS.reset({
        reload: true,
        config: function () {
          this.page.identifier = disqus_identifier
          this.page.url = disqus_url
        }
      })
    }
  </script>
<!-- } -->
</div>

Note: Pjax only handles inline <script> blocks for the container you are switching.

Examples

Clone this repository and run npm run example, which will open the example app in your browser.

CONTRIBUTING

  • ⇄ Pull requests and ★ Stars are always welcome.
  • For bugs and feature requests, please create an issue.
  • Pull requests must be accompanied by passing automated tests (npm test). If the API is changed, please update the Typescript definitions as well (pjax.d.ts).

CHANGELOG

LICENSE

NPM DownloadsLast 30 Days