@georapbox/scroll-top-element

<scroll-top>

A custom element that scrolls to the top of the page. The element is not visible until the user scrolls down a specified amount of pixels. IntersectionObserver API is used under the hood to detect when the element will be visible.

API documentation • Demo

Install

$ npm install --save @georapbox/scroll-top-element

Usage

Script

import { ScrollTop } from './node_modules/@georapbox/scroll-top-element/dist/scroll-top.js';

// Manually define the element.
ScrollTop.defineCustomElement();

Alternatively, you can import the automatically defined custom element.

import './node_modules/@georapbox/scroll-top-element/dist/scroll-top-defined.js';

Markup

<!-- Usage with defaults -->
<scroll-top></scroll-top>

<!-- Customize button's text content and properties -->
<scroll-top visible-after="200px" smooth-scrolling>
  Back to top
</scroll-top>

Style

By default, the component is style-free to remain as less opinionated as possible. However, you can style the various elements of the component using the ::part() CSS pseudo-elements provided for this purpose. Below are demonstrated all available parts for styling.

scroll-top::part(button) {
  /* Custom styling for button */
}

scroll-top::part(button button--hidden) {
  /* Custom styling for button's hidden state */
}

API

Properties/Attributes

Property	Attribute	Type	Default	Description
visibleAfter	visible-after	String	"50vh"	Optional. It defines the distance the user needs to scroll from top so that the button is revealed. The value provided must have a valid absolute or relative length unit, eg px, rem, vh, etc.
smoothScrolling	smooth-scrolling	Boolean	false	Optional. Specifies whether the scrolling should animate smoothly, or happen instantly in a single jump which is the default behavior.
topOffset	top-offset	Number	0	Optional. Specifies the number of pixels along the Y axis to scroll the window.

All properties reflect their values as HTML attributes to keep the element's DOM representation in sync with its JavaScript state.

Slots

Name	Description
(default)	The scroll to top button's content.

CSS Parts

Name	Description
button	The scroll to top button.
button--hidden	The scroll to top button when is hidden.

Methods

Name	Type	Description	Arguments
defineCustomElement	Static	Defines/registers the custom element with the name provided. If no name is provided, the default name is used. The method checks if the element is already defined, hence will skip trying to redefine it.	elementName='scroll-top'

Events

scroll-top:visibility-change - Emitted when the visibility of the element changes.

document.addEventListener('scroll-top:visibility-change', evt => {
  console.log(evt.detail); // => { visible: true }
});

Changelog

For API updates and breaking changes, check the CHANGELOG.

License

The MIT License (MIT)