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 stickyQuery from '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.