pjax
A jQuery plugin that swaps page content via ajax and pushState for faster navigation.defunkt/jquery-pjax
- Stars
- 16.6k
- Forks
- 1.9k
- Licence
- MIT
- Language
- JavaScript
- Last update
- 3.9 years ago
- Type
- Library
No commits in over a year — check for forks or alternatives before adopting.
What it is
pjax is a jQuery plugin that fetches HTML from your server with ajax, replaces one container element on the page with it, and updates the URL with pushState so links, titles and the back button still work. Because scripts and styles are not reloaded, page changes feel faster. The README says the project is largely unmaintained and its feature set is frozen.
- Make links inside a #pjax-container load only the new main content instead of the full page
- Show a loading indicator using the pjax:send and pjax:complete events
- Submit a form in the background with $.pjax.submit and update the container with the response
- Reload the current container's content with $.pjax.reload
Great for
- Developers maintaining an existing jQuery-based website who want faster page-to-page navigation
- Teams migrating a server-rendered site incrementally by opting in specific links with data-pjax
- Projects whose server can return partial HTML when it sees the X-PJAX header
Not ideal for
- New projects: the README says the feature set is frozen and it is unlikely to get new features, so newer frameworks may be a better base
- Sites that do not use jQuery, since the README says it depends on jQuery 1.8 or higher
- Non-developers, since it requires editing page code and server responses
How to get it
- 1
Install with a package manager
You'll need: jQuery 1.8 or higher
Install via npm
$ npm install jquery-pjaxDownload standalone script
curl -LO https://raw.github.com/defunkt/jquery-pjax/master/jquery.pjax.js - 2
Run it
- Include jQuery 1.8 or higher and the jquery.pjax.js script on your page
- Add a container element with id pjax-container to hold the content that gets replaced
- Call $(document).pjax('a', '#pjax-container') or a narrower selector such as 'a[data-pjax]'
- Optionally have your server detect the X-PJAX header and return only the container HTML
- 3
Get the most out of it
- Start with a narrow selector like 'a[data-pjax]' when migrating an existing site
- Set global defaults through $.pjax.defaults, for example the timeout value
- Use the pjax:send and pjax:complete events to show a loading indicator
- Reinitialize other jQuery plugins on new content, as the README advises for page-load-based widgets
- Use the fragment option to extract only part of the ajax response
Downloads
Strengths
- Keeps real URLs, page titles and working back/forward buttons
- Can be adopted gradually by annotating only selected links with data-pjax
- Offers a detailed event lifecycle for hooking in custom behavior
Trade-offs
- The README states the project is largely unmaintained, so future bug fixes are not guaranteed
- Scripts that listen for page load events will not re-run on new content unless you reinitialize them yourself
- Server-side support for the X-PJAX header is needed to get the full speed benefit
How it compares
| Project | Stars | Type | Level | Updated | Best for |
|---|---|---|---|---|---|
| jquery-pjax (this) | 16.6k | Library | intermediate | 3.9 years ago | Developers maintaining an existing jQuery-based website who want faster page-to-page navigation |
| turbolinks | 12.6k | Library | beginner | 5.2 years ago | Existing Ruby on Rails apps that want faster navigation with minimal changes |
Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.