Documentation SW34 Easy Scroll

1. Overview

SW34 Easy Scroll adds smooth scrolling to the public side of a WordPress site. Instead of jumping from one notch to the next, the page glides to its destination with adjustable inertia.

The plugin is built on Lenis, a well-established scrolling library that ships with the plugin. No external server is contacted, and no data ever leaves your site.

What it does

• Smooths scrolling with the mouse wheel and the trackpad.
• Smooths scrolling with the keyboard: arrow keys, Page Up/Down, Space, Home, End. Lenis does not handle the keyboard at all; without this module, the wheel would glide while the keys jump — two contradictory behaviours on the same page.
• Animates anchor links (#section), with an adjustable offset for sticky headers.
• Lets you choose where and for whom smooth scrolling applies: by page, by path, by device type, by role.

What it does not do

These limits are deliberate; knowing them up front avoids disappointment.

• It does not animate scrollable areas inside the page. It drives the page, not the boxes within it. A panel, a wide table or a map that scrolls inside the page keeps its usual scrolling.
• It does not smooth touch scrolling. Native scrolling on a phone is more responsive and better accepted; no setting changes this.
• It produces no rubber-band effect at the edges of the page. The browser cannot scroll past the end of the document.
• It never runs in the admin area, in the Customizer, or inside page builders.

Requirements

2. Installation

From the WordPress plugin directory

1. In your admin area: Plugins → Add New Plugin.
2. Search for SW34 Easy Scroll.
3. Click Install Now, then Activate.

By upload

1. Plugins → Add New Plugin → Upload Plugin.
2. Choose sw34-easy-scroll.zip, then click Install Now.
3. Activate.

After activation

An Easy Scroll menu appears in the admin sidebar. Smooth scrolling is active straight away, with defaults chosen to suit most sites: a 1-second duration, an exponential curve, smoothed wheel and keyboard, animated anchors.

Beyond 2 seconds, scrolling becomes tiresome. Without a top offset, the sections your anchors point to end up underneath the header — measure your header's actual height in pixels.

That's all. The other settings cover specific needs, described below.

4. Settings reference

The screen is laid out in two columns: motion on the left, scope on the right. Each setting is described below with its default value, its limits, and when it is worth changing.

4.1 Master switch

Enable smooth scrolling

Switch — default: on

Turns the plugin off or on across the whole public site.

It is a real switch, not just a flag: when it is off, the plugin loads no files at all on the public side. No JavaScript, no stylesheet. Its performance footprint drops to exactly zero.

The other settings stay editable and are kept while the switch is off; they take effect again when you turn it back on.

4.2 Scroll animation

Animation model

List — default: Fixed duration · values: duration, lerp

Determines how the page reaches its destination.

• Fixed duration — every scroll takes the same time, whatever the distance. Constant, predictable inertia. This is the recommended model, and the one almost every site uses.
• Continuous interpolation (lerp) — the page moves a constant percentage of the remaining distance on each frame. The motion follows the gesture more closely, but the duration varies with the distance.

The two models are mutually exclusive: Duration (seconds) only has an effect in Fixed duration mode, Lerp factor only in lerp mode. The screen automatically hides whichever one does not apply.

Duration (seconds)

Number — default: 1 · range: 0.1 to 5 · Fixed duration mode only

How long the page takes to reach the target position.

Lerp factor

Number — default: 0.1 · range: 0.01 to 1 · lerp mode only

The fraction of the remaining distance covered on each frame.

The lower the value, the more slippery and drawn-out the scroll. The higher it is, the more closely it follows the gesture. 0.1 is a good starting point; 1 removes all inertia.

Easing curve

List — default: Exponential (ease out) — Lenis default · Fixed duration mode only

Distributes the motion over time: start, middle, finish.

4.3 Mouse wheel

Smooth the mouse wheel

Switch — default: on

Applies inertia to mouse wheel and trackpad scrolling.

When off, the wheel goes back to native while the keyboard and anchors stay animated — a combination you rarely want. To turn everything off, use the master switch instead.

Wheel sensitivity

Number — default: 1 · range: 0.1 to 5

Multiplies the distance travelled per wheel notch. 1 is the native behaviour.

Change this with care: visitors have strong expectations about how far one notch takes them. Above 1.5, the page feels like it is running away; below 0.7, like it is resisting.

4.4 Keyboard

Smooth keyboard scrolling

Switch — default: on

Arrow keys, Page Up and Page Down, Space, Home and End glide like the wheel instead of jumping.

Lenis ignores the keyboard entirely. Without this setting, the wheel would be smooth and the keys would not — an inconsistency that is noticed immediately.

The module steps aside whenever a key legitimately belongs to an element:

• input fields, text areas, drop-down lists, buttons;
• audio and video players;
• disclosure widgets, and any element behaving as a button, tab, menu, slider or list box;
• text that can be edited directly on the page;
• any scrollable area inside the page, as long as it has not reached its end;
• any area carrying data-lenis-prevent or listed under Excluded areas (CSS selectors);
• Ctrl, Cmd and Alt, which belong to browser shortcuts.

The keyboard is not intercepted at all for visitors who asked their system for reduced motion.

Distance per arrow press (pixels)

Whole number — default: 120 · range: 20 to 800 · shown when keyboard scrolling is on

The distance covered by one press of an arrow key.

Page Up, Page Down and Space always move by 90% of the screen height, the way browsers do; this setting does not affect them.

4.5 Orientation

Page scroll axis

List — default: Vertical · values: vertical, horizontal, both

The direction the page actually moves in.

Gesture axis taken into account

List — default: Vertical · values: vertical, horizontal, both

The direction of the gesture the plugin listens to.

These two settings work together. The most common case after pure vertical scrolling: a horizontal site driven by the vertical wheel — choose Horizontal for the page scroll axis and Vertical for the gesture axis.

4.6 Anchor links

Animate anchor links

Switch — default: on

#section links glide to their target instead of jumping.

It also works on arrival: an address opened with a fragment, or an anchor followed from another page, is repositioned with the same offset as a click.

Top offset (pixels)

Whole number — default: 0 · range: 0 to 500

The height of your sticky header, so the target section does not end up underneath it.

This is the setting people forget most often. If your anchors land "too low", it is almost always because it is set to 0 while the site has a sticky header.

The admin bar height is added automatically for logged-in users: do not include it in your measurement.

Jump duration (seconds)

Number — default: 1.2 · range: 0.1 to 5

Time taken to reach the anchor. Independent of the regular scroll duration: an anchor jump often covers a much greater distance and deserves a little more time.

4.7 Behaviour

Chain scrolling at the page edges

Switch — default: on

When the page can go no further, the gesture is passed on to the browser or to a scrollable area around the page: pull-to-refresh on mobile, swipe-back on macOS, an enclosing scroll container.

Turn it off if your page lives inside a frame that must not move, or to prevent pull-to-refresh on mobile.

Let nested areas scroll

Switch — default: off

A scrollable area inside the page keeps its own scrolling under the mouse wheel.

This concerns horizontally scrolling tables, side panels, long lists that scroll within their own frame. Note that the keyboard always respects these areas, whatever this setting: stealing the arrow keys from a focused scrollable list would be an accessibility flaw.

Pause automatically when the page is locked

Switch — default: off

Pauses smooth scrolling while the document is frozen.

Useful with modal windows and full-screen menus that freeze the document behind them while they are open. If your mobile menu makes the page move behind it, try this setting.

Stop inertia when navigating away

Switch — default: on

Stops any motion in progress when the visitor leaves the page. Prevents leftover momentum from carrying over to the next page.

4.8 Integration

Expose the instance as window.lenis

Switch — default: off

Publishes the Lenis instance as window.lenis, the name some third-party scripts expect — GSAP ScrollTrigger in particular.

The instance is available as window.SW34EasyScroll.instance either way, whether this setting is checked or not. Only turn it on if a third-party script requires that exact name.

Delete settings on uninstall

Switch — default: off

Left unchecked, your settings survive uninstalling and reinstalling the plugin. Checked, everything is erased from the database on uninstall: the option and the exclusions set page by page.

See Uninstalling and data.

4.9 Where smooth scrolling applies

Respect “reduced motion”

Switch — default: on

Scrolling reverts to native for visitors who asked for less motion in their system's accessibility settings.

Leave this on. This setting only exists for the rare cases where smooth scrolling is an integral part of an experience that makes no sense without it. Turning it off means overriding an explicit accessibility request.

The system setting is followed live: a visitor who changes it during their visit sees the behaviour change without reloading.

Who gets smooth scrolling

List — default: Everyone · values: everyone, logged_out, not_admin

Useful while building a site: native scrolling for you, smooth scrolling for visitors.

Disable on touch devices

Switch — default: off

Phones and tablets keep their native scrolling, whatever their screen width.

Detection is based on the primary pointer type, not on size: a large tablet is still a touch device, and a hybrid laptop plugged into a mouse switches back to smooth scrolling without reloading.

The script is still sent to the browser; it simply does nothing there.

Disable below this screen width (pixels)

Whole number — default: 0 · range: 0 to 3000

0 never disables it. 782 is the WordPress mobile breakpoint.

This setting combines with the previous one: both conditions must be met for smooth scrolling to apply. It is followed live — resizing the window is enough to switch from one mode to the other.

Excluded pages

List of paths, one per line — default: empty

URL paths on which the plugin does not run. The * wildcard is accepted.

/shop/cart
/my-account/*
/checkout

Details that matter:

• Enter a path, not a full URL. A domain pasted by mistake is removed automatically.
• /shop/* also covers /shop on its own.
• Accented paths work: /café is valid.
• Sites installed in a subdirectory are handled: enter /shop, not /blog/shop.
• Up to 100 lines, 200 characters per line.

Excluded areas (CSS selectors)

List of selectors, one per line — default: empty

Native scrolling is handed back to these elements and their contents, for both the mouse wheel and the keyboard.

.et_pb_fullwidth_menu
#my-panel
.leaflet-container

The data-lenis-prevent attribute is already recognised with no setting at all; this list is for elements you cannot edit.

Accented selectors are kept: .rubrique-santé works.

4.10 Reset

Reset settings

Puts every setting on this screen back to the value it had on a fresh install, after you confirm with Yes, reset everything.

The excluded pages and excluded areas are emptied too. Smooth scrolling is switched back on if you had turned it off.

Exclusions set page by page from the editor are not affected.

This cannot be undone.

5. Excluding a page from the editor

Beyond paths, any piece of content can be excluded individually.

1. Open the post, page or other content for editing.
2. Scroll down the sidebar to the Smooth scrolling box.
3. Tick Disable smooth scrolling on this page.
4. Update.

The box is available on all public content types: posts, pages, and your custom post types.

This setting overrides the site-wide settings for this page only. Everything else is unaffected.

6. Ready-made configurations

Six complete configurations, to copy as they are, for the most common needs.

Sticky header and anchors that land right

The most frequent case. Measure the height of your sticky header in pixels, then:

• Anchor links → Animate anchor links: on
• Top offset (pixels): the measured height (80 to 100 with Divi, often)
• Jump duration (seconds): 1.2

Do not add the admin bar to your measurement; it is taken into account automatically.

Keep native scrolling while you work

• Who gets smooth scrolling: Everyone except administrators

Your visitors get the finished result, while you keep instant scrolling to work with. Remember to check the result in a private window before going live.

A shop whose checkout must stay native

• Excluded pages: /cart /checkout /my-account/*

Checkout pages often contain third-party frames and scripts that are sensitive to scrolling. Excluding them saves you from having to diagnose an incident on launch day.

A full-screen menu that makes the page move behind it

Try these in order, checking after each step:

1. Behaviour → Pause automatically when the page is locked: on.
2. If that is not enough, add the menu's selector to Excluded areas (CSS selectors), for example .et_pb_fullwidth_menu.
3. As a last resort, add the data-lenis-prevent attribute to the element if you can edit the template.

A horizontal site

• Page scroll axis: Horizontal
• Gesture axis taken into account: Vertical

The vertical wheel then drives horizontal movement.

As unobtrusive as possible on mobile

• Disable on touch devices: on

Native scrolling on a phone is already excellent. This configuration keeps the effect for devices with a mouse, where it adds something.

7. Accessibility

Smooth scrolling is an animation, and every animation raises an accessibility question. The plugin takes three precautions.

The system "reduced motion" setting is respected. On by default, followed live. A visitor who asks for less motion gets native scrolling back without having to do anything.

The keyboard is never taken away from an element that needs it. The list of protected contexts is detailed in section 4.4. A form, a video player, a drop-down menu or a scrollable area keeps its keys.

Focus follows anchors. After an anchor jump, focus moves to the target section, as native navigation would do. Without this, the next Tab press would start again from the top of the page, and a screen reader would stay on the previous section. The technical attribute added for the purpose is removed as soon as focus moves on.

The address receives the fragment before the animation starts: the Back button works, and the link can still be copied even if the visitor interrupts the movement.

8. Compatibility and performance

Page builders

Smooth scrolling is automatically disabled in the following editing interfaces, with no setting required:

Divi (Visual Builder and Backend Builder), Elementor, Beaver Builder, Oxygen, Bricks, WPBakery, Brizy, Thrive.

It is also turned off in the admin area, in the Customizer, in feeds and in embeds.

If another plugin already loads Lenis

Some themes and plugins already bundle Lenis. The plugin detects this and reuses the copy already present instead of loading a second one: two libraries fighting over the mouse wheel would produce erratic scrolling. You have nothing to do.

Weight on your pages

On the public side, the plugin adds 15.3 KB transferred (47.8 KB uncompressed): the minified Lenis library (18.4 KB, 5.4 KB gzipped), the script that drives it (28.4 KB, 9.2 KB gzipped) and a short stylesheet required to calculate page height (0.6 KB).

No resource is loaded from an external server: everything is served by your own site.

With the master switch off, the plugin loads nothing at all. Its footprint on your pages drops to zero — it is a real switch, not just a flag.

Caching

The plugin is compatible with full-page caching. One precaution only: if you use Who gets smooth scrolling to treat logged-in visitors differently, check that your cache serves uncached pages to logged-in users — otherwise the distinction will have no effect.

9. Troubleshooting

For each symptom: the most likely cause first.

Nothing happens, scrolling stays native

1. Is the master switch on? Easy Scroll menu, at the very top.
2. Are you logged in while "Who gets smooth scrolling" excludes administrators? Check in a private window.
3. Is the page excluded? Look at Excluded pages, and at the Smooth scrolling box in that page's editor.
4. Does a width or touch setting apply? Widen the window to check.
5. Does your system ask for reduced motion? This is common on computers where the option was turned on for some other reason.
6. Are you inside a page builder? The plugin deliberately turns itself off there. Look at the published page.
7. Is a cache serving an old version? Clear it.

Anchors jump instead of gliding

• Check that Animate anchor links is on.
• If the link points to another page, the movement cannot be animated: the browser changes page. The plugin then repositions the section with the right offset, without animation.
• If the link drives a tab or an accordion, it is deliberately left to the component.

Anchors land too low, under the header

Fill in Top offset (pixels) with the height of your sticky header. That is the cause in almost every case.

A panel or a map scrolls the page behind it

Add its CSS selector to Excluded areas (CSS selectors), or add data-lenis-prevent to the element.

Nested areas scroll, but without animation

That is the normal behaviour. Lenis animates the document, not the boxes within it. No setting changes this.

Scrolling is jerky

• A duration that is too long makes any irregularity visible. Try 0.8 s.
• Scroll-triggered animations from another plugin may compete. Turn them off temporarily to isolate the issue.
• On a very long page with many images, check lazy loading.

GSAP ScrollTrigger does not stay in sync

Turn on Expose the instance as window.lenis, then hook ScrollTrigger onto the sw34-easy-scroll:ready event (see the developer appendix).

An error message in the console

[SW34 Easy Scroll] The Lenis library could not be found. — a theme or plugin registered a script under the lenis handle that is not the library. The plugin stepped aside for it. Please report it, stating your theme and active plugins.

10. Appendix — developer reference

10.1 PHP hooks

Six hooks, all prefixed sw34_easy_scroll_.

sw34_easy_scroll_options — filter

Filters the settings as read, before use.

add_filter( 'sw34_easy_scroll_options', function ( $options ) {
    if ( is_front_page() ) {
        $options['duration'] = 1.6;
    }
    return $options;
} );

The return value is sanitised again: an incomplete array or an out-of-range value cannot break the plugin.

sw34_easy_scroll_should_run — filter

The final say on whether the plugin runs, after all internal checks.

add_filter( 'sw34_easy_scroll_should_run', function ( $run ) {
    if ( is_singular( 'documentation' ) ) {
        return false;
    }
    return $run;
} );

sw34_easy_scroll_config — filter

Filters the JavaScript configuration before it is serialised. This is where you enable a Lenis option that the settings screen does not expose.

add_filter( 'sw34_easy_scroll_config', function ( $config ) {
    $config['lenis']['infinite'] = true;
    return $config;
} );

sw34_easy_scroll_post_types — filter

The content types that get the Smooth scrolling box in the editor. By default, all public types.

add_filter( 'sw34_easy_scroll_post_types', function ( $types ) {
    return array_diff( $types, array( 'product' ) );
} );

sw34_easy_scroll_settings_saved — action

Fires after the settings are saved. Receives the sanitised array.

add_action( 'sw34_easy_scroll_settings_saved', function ( $options ) {
    if ( function_exists( 'rocket_clean_domain' ) ) {
        rocket_clean_domain();
    }
} );

sw34_easy_scroll_settings_reset — action

Fires after a reset, in addition to the previous action.

10.2 JavaScript API

The window.SW34EasyScroll object is available as soon as the script runs.

// Scroll to a section programmatically
window.SW34EasyScroll.instance.scrollTo('#pricing', { offset: -90 });

// Pause during an operation
window.SW34EasyScroll.destroy();
// ... then
window.SW34EasyScroll.start();

10.3 Events

Dispatched on document.

document.addEventListener('sw34-easy-scroll:ready', function (e) {
    var lenis = e.detail.lenis;
    lenis.on('scroll', ScrollTrigger.update);
    gsap.ticker.add(function (t) { lenis.raf(t * 1000); });
    gsap.ticker.lagSmoothing(0);
});

The event is dispatched again on every restart — for example when resizing brings the window back above the width threshold. Plan for it if you attach listeners.

10.4 HTML attributes

Recognised with no setting at all, for both the mouse wheel and the keyboard:

<div class="map" data-lenis-prevent>
  <!-- keeps its native scrolling -->
</div>

10.5 PHP constants

10.6 Database storage

The option is autoloaded. Settings are sanitised again on every read: an option corrupted by hand, through WP-CLI or through an SQL import cannot produce an out-of-range value on the public side.

10.7 Full settings schema

11. Uninstalling and data

What the plugin stores

Your settings, and a marker on each page you have explicitly excluded. Nothing else. No table created, no personal data collected, no outgoing network calls, no tracking.

Deactivating

The plugin stops working immediately. Your settings are kept.

Uninstalling

What happens depends on the Delete settings on uninstall setting:

• Unchecked (default) — the settings and per-page exclusions stay in the database. A reinstall finds them intact.
• Checked — your settings and every exclusion set page by page are deleted from the database.

On a multisite network, each site decides for itself according to its own setting. Sites are processed in batches, so uninstalling completes even on a network of several thousand sites.

12. Frequently asked questions

Does the plugin slow my site down? It adds 15.3 KB transferred: the Lenis library (5.4 KB gzipped), an initialisation script and a short stylesheet. With the master switch off, it loads nothing at all.

Does it work with Divi? Yes, and it turns itself off automatically in both the Visual Builder and the Backend Builder. If your theme adds its own anchor scrolling, the Animate anchor links setting takes precedence.

And with WooCommerce? Yes. Product tab links are recognised and left to the component. To exclude the checkout, use Excluded pages.

Can I turn it on for a single page only? Not directly — the logic works the other way round: the plugin applies everywhere, and you exclude. To keep it on one page only, list the others under Excluded pages — or, if you are comfortable with code, use the filter described in the developer appendix.

Why is my touch scrolling not smoothed? On purpose. Native scrolling on a phone is more responsive and better accepted; no setting changes this.

Nested areas are not animated — is that normal? Yes. Lenis animates the document, not the boxes within it.

Can I translate the plugin? It is fully translatable and ships with French and Spanish. The menu label, Easy Scroll, is deliberately kept in languages using the Latin alphabet: it is the product name.

Does the plugin send data anywhere? No. No outgoing network calls, no tracking, no remote resources. The library ships with the plugin.

13. Licence and credits

SW34 Easy Scroll is released under the GPL-2.0-or-later licence by Studio Web 34.

Smooth scrolling is powered by Lenis 1.3.26 by darkroom.engineering, under the MIT licence. Repository: https://github.com/darkroomengineering/lenis The licence text is included in assets/js/LICENSE-lenis.txt.