It’s possible to have an element sticky to the top of the page using the .sticky-top class name from our position utilities, however the Sticky extension takes this one step further by allowing your to change the look-and-feel and behavior of the element as it moves from being unstuck to stuck.
A common use-case is to use the Sticky extension with our headers. The example below uses the Sticky extension to add a box shadow to the header when it is stuck to the top of the page.
All of our themes allow you to make your page header stick to the top of the page using theme settings, but this simple example is intended to illustrate how powerful this functionality can be.
Despite its relative simplicity, there’s no limit to what you can build with this extension.
You can create sticky elements anywhere in the help center and there are various examples built-in to our themes including the page header, which can be configured to stick to the top of the page, and the sidebar table of contents.
The Sticky extension is bundled into all of our themes by default, so you can start using it straight away. The source code can be found within the extensions.(min.)js file in the theme’s Assets folder.
Use data-element="sticky" on the element that you want to become sticky.
<ul class=list-unstyled" data-element="sticky">...</ul>
If data attributes are used you will need to ensure that the allow unsafe HTML setting is enabled within Zendesk Guide.
The Sticky extension can be initialized on a given element using JavaScript:
<div class="header"></div>
<script type="text/javascript">
ready(function() {
new Sticky(document.querySelector('.header'), {
// Options go here
});
});
</script>
Options
Options can be passed via data attributes or JavaScript.
For data attributes, append the option name to data- and use kebab case instead of camel case.
| Name | Type | Default | Description |
|---|---|---|---|
| scrollElement | stringDOM element | window | The scrolling container element that should be observed. |
| offset | number | 0 | The offset amount (positive or negative) to apply before applying stuck and unstuck class names. |
| hide | boolean | false | True if the element should be hidden when the page (or container) is scrolled up. |
| tolerance | number | 8 | How many pixels of movement to allow before the sticky element is hidden. |
| classNames | objectstring | See below | Class names to be applied under various conditions. |
Class names
The classNames option can be provided as a JavaScript object or JSON string. The following table provides an overview of the available properties and their default values.
| Name | Default | Description |
|---|---|---|
| sticky | sticky-top | Applied when the extension is initialized. The default .sticky-top class name sticks the element to the top of the page. |
| unstuck | null | Applied when the element is not stuck to the top or bottom of the scroll element. |
| stuck | null | Applied when the element is stuck to the top or bottom of the scroll element. |
| hidden | is-hidden | Applied when the element is hidden (see hide option above). |
Events
| Name | Description |
|---|---|
sticky:initialize | Fires when the extension is initialized. |
sticky:stuck | Fires when the element is stuck to the top or bottom of the scroll element. |
sticky:unstuck | Fires when the element is unstuck. |
sticky:hidden | Fires when the element is hidden. |
sticky:shown | Fires when the element is shown. |
document.addEventListener('sticky.stuck', function(e) {
// Do something...
});
