Guide · Open source
How to use jquery-pjax: install, set up links and handle events
Updated · written with AI from the project's own documentation and checked against our catalogue data
jquery-pjax (pjax) is a jQuery plugin that loads HTML from your server with ajax, replaces one container element on the page, and updates the URL with pushState. This guide shows how to install it, turn it on for selected links, let your server return partial HTML, and handle its events. It assumes you already maintain a jQuery-based website and are comfortable editing page code and server responses.
pjaxdefunkt/jquery-pjax · ★ 16.6k · MIT Install options & downloads Quick start
- 1Confirm jQuery 1.8+. Make sure your page already loads jQuery version 1.8 or higher.
- 2Install the plugin. Run npm install jquery-pjax, or download jquery.pjax.js and include it after jQuery.
- 3Add a container. Choose the element that will be replaced, such as #pjax-container.
- 4Mark links with data-pjax. Add data-pjax to the links you want to enable during migration.
- 5Call $.fn.pjax. Use $(document).pjax with a selector for those links and your container.
- 6Support partial responses. Have the server check the X-PJAX header and render only the container HTML.
- 7Handle events. Listen for pjax:send and pjax:complete to show a loading indicator and reinitialize widgets.
Check the requirements before you install
pjax depends on jQuery 1.8 or higher, so your page must already load a compatible jQuery version before pjax is loaded.
The README states that the project is largely unmaintained and its feature set is frozen. It may still receive important bug fixes, but new features are unlikely. This makes it a better fit for maintaining an existing site than for starting a new one.
- jQuery 1.8 or higher
- A server that can return HTML for a page, and optionally detect the X-PJAX header
Install jquery-pjax with npm or as a standalone script
If you use a package manager, install it with npm. If you prefer a single file, download the standalone script and include it in your web page after jQuery.
The README gives both options as shown below.
$ npm install jquery-pjax
curl -LO https://raw.github.com/defunkt/jquery-pjax/master/jquery.pjax.jsEnable pjax on links with a selector
The simplest setup enables pjax on all links on the page and names the container element. The README notes that this is the most common usage.
If you are migrating an existing site, avoid enabling pjax everywhere at once. Instead, mark the links you want with data-pjax and use a narrower selector. The README also offers a selector that matches data-pjax links inside a data-pjax container.
- Use 'a[data-pjax]' to match only annotated links.
- Use '[data-pjax] a, a[data-pjax]' to match links inside a data-pjax container as well as annotated links.
$(document).pjax('a', '#pjax-container')
$(document).pjax('[data-pjax] a, a[data-pjax]', '#pjax-container')Let the server return partial HTML for pjax requests
Ideally, your server checks for the X-PJAX HTTP header and renders only the HTML that replaces the container, without the rest of the page layout. The README gives a Ruby on Rails example. Where the server does not do this, pjax still fetches the full page, but the README says the speed gain from partial rendering is lost.
The README also points to Turbolinks as a more automatic option for Rails, and to a list of pjax plugins for other server frameworks.
def index
if request.headers['X-PJAX']
render :layout => false
end
endTune the options
Options are passed as an object as the third argument. The README lists the defaults in a table. Some of the most useful are timeout (650 ms by default, after which a full refresh is forced), push (true by default, adds a history entry), maxCacheLength (20 by default), and scrollTo (0 by default; pass false to keep the scroll position).
You can change defaults for all calls by writing to $.pjax.defaults.
- timeout: ajax timeout in milliseconds before a full refresh
- push: use pushState to add a browser history entry
- replace: replace the URL without adding a history entry
- maxCacheLength: maximum cache size for previous container contents
- scrollTo: vertical position after navigation; false avoids changing it
- fragment: CSS selector for the fragment to extract from the response
$.pjax.defaults.timeout = 1200Use events to add loading indicators and custom behaviour
pjax fires events during each navigation. The pjax:send and pjax:complete pair is recommended for a loading indicator, because they only fire when a real XHR request is made, not when content comes from cache.
The pjax:timeout and pjax:error events hard refresh the page unless you cancel them. The README shows how to cancel pjax:timeout to stop that fallback, for example when a spinner is shown.
- pjax:beforeReplace fires before the new HTML is inserted
- pjax:success fires after the content is replaced
- pjax:popstate fires on browser Back/Forward and sets a direction property
$(document).on('pjax:send', function() {
$('#loading').show()
})
$(document).on('pjax:complete', function() {
$('#loading').hide()
})Reinitialize widgets after new content loads
pjax inserts new content without a page refresh, so plugins that only run on DOMContentLoaded will not see the new elements. The README advises reinitializing plugins and widgets when new page content arrives, which is usually a good idea.
Use $.pjax.click or $.pjax.submit when you need finer control over click or form handling. Use $.pjax.reload to re-request the current URL into the container.
What people use it for
- Speeding up page-to-page navigation on an existing jQuery-based website
- Migrating a server-rendered site one link at a time by opting in links with data-pjax
- Showing a loading indicator during navigation using pjax:send and pjax:complete
- Re-requesting the current page into a container with $.pjax.reload after a change
Frequently asked questions
How do I install jquery-pjax?
Install it with npm using npm install jquery-pjax, or download the standalone jquery.pjax.js file with curl from the project's GitHub raw URL. Include it in your page after jQuery 1.8 or higher.
What are the requirements for jquery-pjax?
The README says pjax depends on jQuery 1.8 or higher. The server side is optional, but returning partial HTML when it sees the X-PJAX header makes navigation faster.
Is jquery-pjax free to use?
The project is released under the MIT licence, as listed in the repository. Check the licence file in the repository for the full terms.
Is jquery-pjax still maintained?
The README says the project is largely unmaintained. It might receive important bug fixes, but its feature set is frozen and new features are unlikely.
What are alternatives to jquery-pjax?
The README lists Turbolinks, Turbo (Hotwire), HTMX and Barba.js as comparable projects. Turbolinks is mentioned specifically as a more automatic option for Rails.
Why does pjax not work on my links?
Check that jQuery 1.8 or higher is loaded, that pjax is called with the right selector and container, and that the container exists on the page. The README also notes that scripts are not re-run, so plugins may need reinitializing after new content loads.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use jquery-pjax if you maintain an existing jQuery website and want faster navigation with minimal changes, especially by opting in links one at a time with data-pjax. Pick something else for a new project, a site that does not use jQuery, or if you need active maintenance, since the README says the feature set is frozen.
Install options & downloads