PHPackages                             yiisoft/jquery-pjax - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. yiisoft/jquery-pjax

Abandoned → install via bower insteadLibrary[Framework](/categories/framework)

yiisoft/jquery-pjax
===================

pushState + ajax = pjax, a forked maintainted by the Yii Framework core developers

v2.0.5(10y ago)146218.6k↑735.7%41[1 issues](https://github.com/yiisoft/jquery-pjax/issues)[1 PRs](https://github.com/yiisoft/jquery-pjax/pulls)1MITJavaScriptCI passing

Since Mar 12Pushed 1w ago20 watchersCompare

[ Source](https://github.com/yiisoft/jquery-pjax)[ Packagist](https://packagist.org/packages/yiisoft/jquery-pjax)[ Docs](https://github.com/yiisoft/jquery-pjax#readme)[ RSS](/packages/yiisoft-jquery-pjax/feed)WikiDiscussions master Synced yesterday

READMEChangelog (10)Dependencies (1)Versions (7)Used By (1)

pjax = pushState + ajax, Yii 2.0 fork with enhancements
=======================================================

[](#pjax--pushstate--ajax-yii-20-fork-with-enhancements)

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

[](#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
------------

[](#installation)

pjax depends on jQuery 1.8 or higher.

### Yii 2.0

[](#yii-20)

There's no need to install library manually since it comes pre-installed with Yii 2.0.

### bower

[](#bower)

```
$ bower install yii2-pjax

```

### standalone script

[](#standalone-script)

Or, add `yii2-pjax` to your app's `bower.json`.

```
  "dependencies": {
    "yii2-pjax": "latest"
  }
```

### standalone

[](#standalone)

pjax can be downloaded directly into your app's public directory - just be sure you've loaded jQuery first. Download and include `jquery.pjax.js` in your web page:

```
curl -LO https://raw.github.com/yiisoft/jquery-pjax/master/jquery.pjax.js

```

Usage
-----

[](#usage)

### `$.fn.pjax`

[](#fnpjax)

The simplest and most common use of pjax looks like this:

```
$(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:

```
$(document).pjax('[data-pjax] a, a[data-pjax]', '#pjax-container')
```

#### Server-side configuration

[](#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:

```
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](https://github.com/rails/turbolinks).

[Check if there is a pjax plugin](https://gist.github.com/4283721) for your favorite server framework.

Also check out [RailsCasts #294: Playing with PJAX](http://railscasts.com/episodes/294-playing-with-pjax).

#### Arguments

[](#arguments)

The synopsis for the `$.fn.pjax` function is:

```
$(document).pjax(selector, [container], options)
```

1. `selector` is a string to be used for click [event delegation](http://api.jquery.com/on/).
2. `container` is a string selector that uniquely identifies the pjax container.
3. `options` is an object with keys described below.

##### pjax options

[](#pjax-options)

keydefaultdescription`timeout`650ajax timeout in milliseconds after which a full refresh is forced`push`trueuse [pushState](https://developer.mozilla.org/en-US/docs/Web/Guide/API/DOM/Manipulating_the_browser_history#Adding_and_modifying_history_entries) to add a browser history entry upon navigation`replace`falsereplace URL without adding browser history entry`maxCacheLength`20maximum cache size for previous container contents`version`a string or function returning the current pjax version`scrollTo`0vertical position to scroll to after navigation. To avoid changing scroll position, pass `false`. If set to `true` page will scroll to the pjax container. Can also be be a callback function with context and current hash passed in as parameters. E.g. `function (context, hash) { if (!hash) return $(context).offset().top; }``scrollOffset`0vertical offset that gets added to `scrollTo`. Can be a callback function with the current `scrollTo` value passed as a parameter.`type``"GET"`see [$.ajax](http://api.jquery.com/jQuery.ajax/)`dataType``"html"`see [$.ajax](http://api.jquery.com/jQuery.ajax/)`container`CSS selector for the element where content should be replaced`url`link.hrefa string or function that returns the URL for the ajax request`target`linkeventually the `relatedTarget` value for [pjax events](#events)`fragment`CSS selector for the fragment to extract from ajax response`pushRedirect`falsewhether to add a browser history entry upon redirect`replaceRedirect`truewhether to replace URL without adding a browser history entry upon redirect`skipOuterContainers`falseWhen pjax containers are nested and this option is true, the closest pjax block will handle the event. Otherwise, the top container will handle the event`ieRedirectCompatibility`trueWhether to add `X-Ie-Redirect-Compatibility` header for the request on IE. Fixes IE error on 302 redirect without `Location` headerYou can change the defaults globally by writing to the `$.pjax.defaults` object:

```
$.pjax.defaults.timeout = 1200
```

### `$.pjax.click`

[](#pjaxclick)

This is a lower level function used by `$.fn.pjax` itself. It allows you to get a little more control over the pjax event handling.

This example uses the current click context to set an ancestor element as the container:

```
if ($.support.pjax) {
  $(document).on('click', 'a[data-pjax]', function(event) {
    var container = $(this).closest('[data-pjax-container]')
    var containerSelector = '#' + container.id
    $.pjax.click(event, {container: containerSelector})
  })
}
```

**NOTE** Use the explicit `$.support.pjax` guard. We aren't using `$.fn.pjax` so we should avoid binding this event handler unless the browser is actually going to use pjax.

### `$.pjax.submit`

[](#pjaxsubmit)

Submits a form via pjax.

```
$(document).on('submit', 'form[data-pjax]', function(event) {
  $.pjax.submit(event, '#pjax-container')
})
```

### `$.pjax.reload`

[](#pjaxreload)

Initiates a request for the current URL to the server using pjax mechanism and replaces the container with the response. Does not add a browser history entry.

```
$.pjax.reload('#pjax-container', options)
```

### `$.pjax`

[](#pjax)

Manual pjax invocation. Used mainly when you want to start a pjax request in a handler that didn't originate from a click. If you can get access to a click `event`, consider `$.pjax.click(event)` instead.

```
function applyFilters() {
  var url = urlForFilters()
  $.pjax({url: url, container: '#pjax-container'})
}
```

Events
------

[](#events)

All pjax events except `pjax:click` & `pjax:clicked` are fired from the pjax container element.

 event cancel arguments notes event lifecycle upon following a pjaxed link `pjax:click` ✔︎ `options` fires from a link that got activated; cancel to prevent pjax `pjax:beforeSend` ✔︎ `xhr, options` can set XHR headers `pjax:start`  `xhr, options`  `pjax:send`  `xhr, options`  `pjax:clicked`  `options` fires after pjax has started from a link that got clicked `pjax:beforeReplace`  `contents, options` before replacing HTML with content loaded from the server `pjax:success`  `data, status, xhr, options` after replacing HTML content loaded from the server `pjax:timeout` ✔︎ `xhr, options` fires after `options.timeout`; will hard refresh unless canceled `pjax:error` ✔︎ `xhr, textStatus, error, options` on ajax error; will hard refresh unless canceled `pjax:complete`  `xhr, textStatus, options` always fires after ajax, regardless of result `pjax:end`  `xhr, options`  event lifecycle on browser Back/Forward navigation `pjax:popstate`   event `direction` property: "back"/"forward" `pjax:start`  `null, options` before replacing content `pjax:beforeReplace`  `contents, options` right before replacing HTML with content from cache `pjax:end`  `null, options` after replacing content`pjax:send` & `pjax:complete` are a good pair of events to use if you are implementing a loading indicator. They'll only be triggered if an actual XHR request is made, not if the content is loaded from cache:

```
$(document).on('pjax:send', function() {
  $('#loading').show()
})
$(document).on('pjax:complete', function() {
  $('#loading').hide()
})
```

An example of canceling a `pjax:timeout` event would be to disable the fallback timeout behavior if a spinner is being shown:

```
$(document).on('pjax:timeout', function(event) {
  // Prevent default timeout redirection behavior
  event.preventDefault()
})
```

Advanced configuration
----------------------

[](#advanced-configuration)

### Reinitializing plugins/widget on new page content

[](#reinitializing-pluginswidget-on-new-page-content)

The whole point of pjax is that it fetches and inserts new content *without*refreshing the page. However, other jQuery plugins or libraries that are set to react on page loaded event (such as `DOMContentLoaded`) will not pick up on these changes. Therefore, it's usually a good idea to configure these plugins to reinitialize in the scope of the updated page content. This can be done like so:

```
$(document).on('ready pjax:end', function(event) {
  $(event.target).initializeMyPlugin()
})
```

This will make `$.fn.initializeMyPlugin()` be called at the document level on normal page load, and on the container level after any pjax navigation (either after clicking on a link or going Back in the browser).

### Response types that force a reload

[](#response-types-that-force-a-reload)

By default, pjax will force a full reload of the page if it receives one of the following responses from the server:

- Page content that includes `` when `fragment` selector wasn't explicitly configured. Pjax presumes that the server's response hasn't been properly configured for pjax. If `fragment` pjax option is given, pjax will extract the content based on that selector.
- Page content that is blank. Pjax assumes that the server is unable to deliver proper pjax contents.
- HTTP response code that is 4xx or 5xx, indicating some server error.

### Affecting the browser URL

[](#affecting-the-browser-url)

If the server needs to affect the URL which will appear in the browser URL after pjax navigation (like HTTP redirects work for normal requests), it can set the `X-PJAX-URL` header:

```
def index
  request.headers['X-PJAX-URL'] = "http://example.com/hello"
end
```

### Layout Reloading

[](#layout-reloading)

Layouts can be forced to do a hard reload when assets or html changes.

First set the initial layout version in your header with a custom meta tag.

```

```

Then from the server side, set the `X-PJAX-Version` header to the same.

```
if request.headers['X-PJAX']
  response.headers['X-PJAX-Version'] = "v123"
end
```

Deploying a deploy, bumping the version constant to force clients to do a full reload the next request getting the new layout and assets.

###  Health Score

56

—

FairBetter than 97% of packages

Maintenance63

Regular maintenance activity

Popularity48

Moderate usage in the ecosystem

Community36

Small or concentrated contributor base

Maturity67

Established project with proven stability

 Bus Factor2

2 contributors hold 50%+ of commits

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~101 days

Total

7

Last Release

3888d ago

Major Versions

v1.8.0-patch1 → v2.0.02014-03-20

### Community

Maintainers

![](https://www.gravatar.com/avatar/261a6249c6f605f3956a2fae40fbb813f6b2e1e6f2bf806180c851a965426e54?d=identicon)[cebe](/maintainers/cebe)

![](https://www.gravatar.com/avatar/fc29e4e7068a00fe9b9db37b8aadda1db6020adcacef810461e47b99c2b150e6?d=identicon)[samdark](/maintainers/samdark)

![](https://www.gravatar.com/avatar/23416c58e0dce33a8369451a4ca0e28666373594027debc10184b37ade6a926b?d=identicon)[qiangxue](/maintainers/qiangxue)

![](https://www.gravatar.com/avatar/ccb75e3312d6bd454ea445ea308139fd185a4ca906ca5df21cc66e6a35de25a3?d=identicon)[SilverFire](/maintainers/SilverFire)

---

Top Contributors

[![josh](https://avatars.githubusercontent.com/u/137?v=4)](https://github.com/josh "josh (212 commits)")[![mislav](https://avatars.githubusercontent.com/u/887?v=4)](https://github.com/mislav "mislav (112 commits)")[![defunkt](https://avatars.githubusercontent.com/u/2?v=4)](https://github.com/defunkt "defunkt (74 commits)")[![SilverFire](https://avatars.githubusercontent.com/u/4499203?v=4)](https://github.com/SilverFire "SilverFire (41 commits)")[![samdark](https://avatars.githubusercontent.com/u/47294?v=4)](https://github.com/samdark "samdark (15 commits)")[![anttimattila](https://avatars.githubusercontent.com/u/1428114?v=4)](https://github.com/anttimattila "anttimattila (7 commits)")[![qiangxue](https://avatars.githubusercontent.com/u/993322?v=4)](https://github.com/qiangxue "qiangxue (6 commits)")[![cebe](https://avatars.githubusercontent.com/u/189796?v=4)](https://github.com/cebe "cebe (5 commits)")[![chris123457](https://avatars.githubusercontent.com/u/81005631?v=4)](https://github.com/chris123457 "chris123457 (4 commits)")[![0b10011](https://avatars.githubusercontent.com/u/1123348?v=4)](https://github.com/0b10011 "0b10011 (4 commits)")[![tof06](https://avatars.githubusercontent.com/u/2961054?v=4)](https://github.com/tof06 "tof06 (3 commits)")[![AlexHill](https://avatars.githubusercontent.com/u/1011483?v=4)](https://github.com/AlexHill "AlexHill (3 commits)")[![derekisbusy](https://avatars.githubusercontent.com/u/5118781?v=4)](https://github.com/derekisbusy "derekisbusy (3 commits)")[![eval](https://avatars.githubusercontent.com/u/290596?v=4)](https://github.com/eval "eval (3 commits)")[![SamyPesse](https://avatars.githubusercontent.com/u/845425?v=4)](https://github.com/SamyPesse "SamyPesse (3 commits)")[![spantaleev](https://avatars.githubusercontent.com/u/388669?v=4)](https://github.com/spantaleev "spantaleev (3 commits)")[![squeedee](https://avatars.githubusercontent.com/u/27838?v=4)](https://github.com/squeedee "squeedee (3 commits)")[![sshirokov](https://avatars.githubusercontent.com/u/40149?v=4)](https://github.com/sshirokov "sshirokov (3 commits)")[![drock](https://avatars.githubusercontent.com/u/164126?v=4)](https://github.com/drock "drock (2 commits)")[![rf-](https://avatars.githubusercontent.com/u/345106?v=4)](https://github.com/rf- "rf- (2 commits)")

---

Tags

ajaxpjax

### Embed Badge

![Health badge](/badges/yiisoft-jquery-pjax/health.svg)

```
[![Health](https://phpackages.com/badges/yiisoft-jquery-pjax/health.svg)](https://phpackages.com/packages/yiisoft-jquery-pjax)
```

###  Alternatives

[laravel/dusk

Laravel Dusk provides simple end-to-end testing and browser automation.

1.9k39.6M299](/packages/laravel-dusk)[nineinchnick/edatatables

Grid widget for the Yii Framework, wrapper for the DataTables jQuery plugin

173.2k](/packages/nineinchnick-edatatables)[link-cloud/fast-hyperf

LinkCloud Fast Hyperf

241.2k1](/packages/link-cloud-fast-hyperf)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)