+0
Daily
16,622
stars
1,913
forks
536
watchers
280
prs
452
issues
11
releases
README
pjax = pushState + ajax
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.
pjax works by fetching HTML from your server via ajax and replacing the content
of a container element on your page with the loaded HTML. It then updates the
current URL in the browser using pushState. This results in faster page
navigation for two reasons:
No page resources (JS, CSS) get re-executed or re-applied;
If the server is configured for pjax, it can render only partial page
contents and thus avoid the potentially costly full layout render.
Status of this project
jquery-pjax is largely unmaintained at this point. It might continue to
receive important bug fixes, but _its feature set is frozen_ and it's unlikely
that it will get new features or enhancements.
Installation
pjax depends on jQuery 1.8 or higher.
npm
$ npm install jquery-pjax
standalone script
Download and include jquery.pjax.js in your web page:
curl -LO https://raw.github.com/defunkt/jquery-pjax/master/jquery.pjax.js
Usage
$.fn.pjax
The simplest and most common use of pjax looks like this:
javascript
$(document).pjax('a', 'pjax-container')
This will enable pjax on all links on the page and designate the container as pjax-container.
If you are migrating an existing site, you probably don't want to enable pjax
everywhere just yet. Instead of using a global selector like a, try annotating
pjaxable links with data-pjax, then use 'a[data-pjax]' as your selector. Or,
try this selector that matches any links inside a container:
javascript
$(document).pjax('[data-pjax] a, a[data-pjax]', 'pjax-container')
Server-side configuration
Ideally, your server should detect pjax requests by looking at the special
X-PJAX HTTP header, and render only the HTML meant to replace the contents of
the container element (pjax-container in our example) without the rest of
the page layout. Here is an example of how this might be done in Ruby on Rails:
ruby
def index
if request.headers['X-PJAX']
render :layout = false
end
end
If you'd like a more automatic solution than pjax for Rails check out [Turbolinks][].
[Check if there is a pjax plugin][plugins] for your favorite server framework.
Also check out [RailsCasts 294: Playing with PJAX][railscasts].
Arguments
The synopsis for the $.fn.pjax function is:
javascript
$(document).pjax(selector, [container], options)
1. selector is a string to be used for click [event delegation][$.fn.on].
2. container is a string selector that uniquely identifies the pjax container.
3. options is an object with keys described below.
pjax options
key | default | description
----|---------|------------
timeout | 650 | ajax timeout in milliseconds after which a full refresh is forced
push | true | use [pushState][] to add a browser history entry upon navigation
replace | false | replace URL without adding browser history entry
maxCacheLengTop issues
#331External scripts are evaluated async43 comments · 2013-11-06#498Calling pjax only after CSS transition out has ended?23 comments · 2015-03-08#451No event is fired before current contents are cached14 comments · 2014-11-04#321Back and forward bug13 comments · 2013-10-01#453HTML5 video reload10 comments · 2014-11-06#493Question: Is it possible to get data attribute from fragment or fragment's parent?7 comments · 2015-02-25#596Can't back to #hashed state6 comments · 2015-11-23#520No request on back button6 comments · 2015-04-14
Latest release
jquery-pjax 2.0.1 v2.0.1 2017-05-20Fix blurring current active element within pjax container Remove extra & after stripping internal query params Handle documents with no or empty tag Fix npm warnings about package.json Add eslint to project