defunkt /jquery-pjax

pushState + ajax = pjax

★ 16,622⑂ 1,913👁 536⑃ 280● 452▤ 11
JavaScriptMITCreated 2011-02-26pjax.herokuapp.com
Download: jquery-pjax 2.0.1jquery-pjax-2.0.1 ↓2.0.12017-05-20
+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
maxCacheLeng

Top issues

Latest release

jquery-pjax 2.0.1 v2.0.1 2017-05-20
Fix 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

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON