sticky-query v1.0.1
StickyQuery
A tiny, vanilla JS plugin to help you persist query strings across your website. No dependencies.
How It Works
StickyQuery works by reading existing parameters in the URL and applying them to links on your page.
That way, when the user clicks on a link, the query string will remain as the user navigates from page to page.
Author Support
If this plugin helps you out, you can buy me a coffee to keep me going! ☕🙂 much appreciated!
Requirements
Browser Support
StickyQuery is compatible with all modern browsers, and IE11.
Installation
Direct Download
Compiled and production-ready code can be found in the dist
directory.
You can download the files directly from GitHub (zip).
<script src="path/to/sticky-query.min.js"></script>
NPM
# npm
npm install sticky-query
# yarn
yarn add sticky-query
# ES6
import 'sticky-query';
# ES5
var stickyQuery = require('sticky-query');
CDN
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/sticky-query@1/dist/sticky-query.min.js"></script>
Usage
Just before the closing </body>
tag (or in your own DOM Content handler function) initialize StickyQuery as follows:
<script>
stickyQuery.init({
// options
});
</script>
Note: By default StickyQuery will be applied to all links on your page except:
<!-- Internal anchor links -->
<a href="#about-us">About us</a>
<!-- JavaScript dummy links -->
<a href="javascript:;">Sign up</a>
<!-- Links that already include a query string -->
<a href="https://google.com/?utm_content=example">Go to google</a>
<!-- Links with the class "sticky-query-ignore" -->
<a class="sticky-query-ignore" href="/about-us">About us</a>
You can change this behavior and add your own rules by passing Options to the init()
method.
Options
<script>
stickyQuery.init({
allowedKeys: 'utm_content, utm_campaign',
excludeCustom: '.my-ignore',
excludeAnchors: true,
excludeJavascript: true,
excludeHasQuery: true,
});
</script>
Option | Type | Default | Description |
---|---|---|---|
allowedKeys | String | null | Limit which parameters will be persisted (separate multiple keys with commas). |
excludeCustom | String | null | Stop from affecting certain links of your choosing (accepts a CSS selector). |
excludeAnchors | Boolean | true | Stop from affecting internal anchor links that point to the current page. |
excludeJavascript | Boolean | true | Stop from affecting javascript dummy links. |
excludeHasQuery | Boolean | true | Stop from affecting links that already have a URL query string. |
Callbacks
stickyQuery.init({
callbackBefore: function() {
//
},
callbackAfter: function() {
//
},
});
Callback | Params | Description |
---|---|---|
callbackBefore | none | Before initialization. |
callbackAfter | none | After initialization. |
Methods
Method | Arguments | Description |
---|---|---|
init | options: object | Initializes StickyQuery. |
destroy | none | Destroys StickyQuery. |
Implementation tricks and examples
Exclude links that contain a certain URL
<script>
stickyQuery.init({
excludeCustom: '[href*=google.com]',
});
</script>
Only apply StickyQuery to links that have a specific selector
<script>
stickyQuery.init({
excludeCustom: ':not(.sticky-query-apply)',
});
</script>
License
The code is available under the MPL 2.0 License.