Back to Top
Back to Top provides a floating button that appears when users scroll down, allowing quick return to the page top. Perfect for long pages, documentation, and content-heavy sites.
Key Features
- Auto Show/Hide - Appears after scrolling threshold
- Smooth Scrolling - Configurable animation duration
- Positioning - Bottom-right, bottom-left, or custom
- Callbacks - onShow and onHide events
Basic Usage
const backToTop = Domma.elements.backToTop('#back-to-top', {
showAfter: 300,
duration: 600,
position: 'bottom-right'
});
Getting Started
Add a back to top button to your page in three simple steps
Step 1: Add Button Element
Create a button element with a class and unique ID:
<button id="back-to-top" class="back-to-top-btn">↑</button>
Step 2: Include Domma
Add Domma CSS and JavaScript to your page:
<!-- CSS -->
<link rel="stylesheet" href="dist/domma.css">
<link rel="stylesheet" href="dist/elements.css">
<!-- JavaScript -->
<script src="dist/domma.min.js"></script>
Step 3: Initialize the Button
Call Domma.elements.backToTop() to activate the button:
Domma.elements.backToTop('#back-to-top', {
showAfter: 300, // Show after scrolling 300px
duration: 500 // Scroll animation duration in ms
});
Quick Start
Simple Back to Top Button
Scroll down this demo area to see the button appear
Scroll down...
Keep scrolling...
Almost there...
You should see the button now!
<button id="back-to-top" class="back-to-top-btn">↑</button>
<script>
Domma.elements.backToTop('#back-to-top', {
showAfter: 200,
duration: 500
});
</script>
Native Web Component
<domma-back-to-top> tag below for better style isolation and framework compatibility.
Native Tag Syntax
Use the native <domma-back-to-top> Web Component directly in HTML with attributes for configuration:
<!-- Basic Web Component -->
<domma-back-to-top></domma-back-to-top>
<!-- Configured Web Component -->
<domma-back-to-top
show-after="400"
duration="500"
position="bottom-left"
offset="20"
></domma-back-to-top>
<!-- With Scroll Container -->
<domma-back-to-top
target="#scrollable-content"
show-after="300"
></domma-back-to-top>
Live Web Component Demo
Scroll down to see the native Web Component appear
Web Component Example
This uses <domma-back-to-top> tag
Shadow DOM provides style isolation
Reactive attribute updates supported
Available Attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
show-after |
Number | viewport height | Pixels to scroll before showing |
duration |
Number | 300 |
Scroll animation duration in ms |
position |
String | 'bottom-right' |
Position: bottom-right, bottom-left |
offset |
Number | 16 |
Distance from screen edge in px |
target |
String | window |
CSS selector for scroll container |
z-index |
Number | 1000 |
Z-index for stacking context |
visible |
Boolean | false |
Initial visibility state |
JavaScript API
Access the Web Component instance and call methods programmatically:
// Get the Web Component element
const btn = $('domma-back-to-top')[0];
// Call methods
btn.scroll(); // Scroll to top
btn.show(); // Show button immediately
btn.hide(); // Hide button
btn.toggle(); // Toggle visibility
btn.isVisible(); // Check visibility → boolean
btn.getButton(); // Get button element
// Update attributes programmatically
btn.setShowAfter(500); // Change threshold
btn.setPosition('bottom-left'); // Change position
btn.setOffset(24); // Change offset
// Listen for events
btn.addEventListener('show', (e) => {
console.log('Button appeared');
});
btn.addEventListener('hide', (e) => {
console.log('Button hidden');
});
Reactive Attributes Demo
Attributes update reactively!
Try the buttons above
Event Handling
<domma-back-to-top id="my-btn"></domma-back-to-top>
<script>
const btn = $('#my-btn')[0];
// Listen for show event
btn.addEventListener('show', (e) => {
console.log('Button became visible');
$('#status')[0].textContent = 'Visible';
});
// Listen for hide event
btn.addEventListener('hide', (e) => {
console.log('Button became hidden');
$('#status')[0].textContent = 'Hidden';
});
</script>
Benefits of Web Components
- Shadow DOM Isolation: Styles don't leak in or out
- Native Browser API: No framework required
- Reactive Attributes: Changes update automatically
- Framework Agnostic: Works with React, Vue, Angular, Svelte
- Custom Events: Standard DOM event system
- Backwards Compatible: Traditional API still available
Using with Frameworks
React
import { useRef, useEffect } from 'react';
function MyComponent() {
const btnRef = useRef(null);
useEffect(() => {
const btn = btnRef.current;
const handleShow = () => console.log('Visible');
btn.addEventListener('show', handleShow);
return () => btn.removeEventListener('show', handleShow);
}, []);
return <domma-back-to-top ref={btnRef} show-after="300" />;
}
Vue
<template>
<domma-back-to-top
ref="backToTop"
:show-after="300"
:duration="500"
@show="onShow"
@hide="onHide"
></domma-back-to-top>
</template>
<script>
export default {
methods: {
onShow() { console.log('Visible'); },
onHide() { console.log('Hidden'); }
},
mounted() {
this.$refs.backToTop.scroll();
}
};
</script>
Angular
import { Component, ViewChild, ElementRef } from '@angular/core';
@Component({
selector: 'app-my-component',
template: `
<domma-back-to-top
#backToTop
show-after="300"
(show)="onShow()"
(hide)="onHide()"
></domma-back-to-top>
`
})
export class MyComponent {
@ViewChild('backToTop') backToTop!: ElementRef;
onShow() { console.log('Visible'); }
onHide() { console.log('Hidden'); }
scrollToTop() {
this.backToTop.nativeElement.scroll();
}
}
CSS Part Customization
Customize Web Component styles using CSS ::part() selectors:
/* Target the button inside Shadow DOM */
domma-back-to-top::part(button) {
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
border: none;
width: 50px;
height: 50px;
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);
}
domma-back-to-top::part(button):hover {
transform: translateY(-2px) scale(1.15);
box-shadow: 0 6px 16px rgba(0, 0, 0, 0.4);
}
Tutorial
Build a back to top button with custom styling and callbacks.
Implementation Guide
Scroll down to see the custom back to top button with callbacks tracking visibility state...
Understanding Back to Top
The back to top button provides a quick way to return to the page start without manually scrolling.
When to Use
Best for long-form content, documentation pages, blog articles, and dashboards with extensive data.
Customization Options
Configure appearance threshold, animation duration, positioning, and event callbacks to match your design.
User Experience
The button automatically shows when scrolling past the threshold and hides when near the top of the page.
Button status:
const backToTop = Domma.elements.backToTop('#back-to-top', {
showAfter: 300,
duration: 600,
position: 'bottom-right',
offset: { bottom: 20, right: 20 },
target: '#scrollable-container',
onShow: () => {
console.log('Button shown');
$('#status')[0].textContent = 'Visible';
},
onHide: () => {
console.log('Button hidden');
$('#status')[0].textContent = 'Hidden';
}
});
Examples
Different Positions
Scroll to see buttons at different positions...
Bottom right button appears first
You should see the buttons now
Custom Duration
Try different scroll speeds...
Scroll down to see the button
Programmatic Control
Use buttons above to control the back to top button
Scroll position tracked
Best Practices
Accessibility
- Keyboard Access - Ensure button is keyboard focusable
- ARIA Label - Add
aria-label="Back to top"for screen readers - Focus Visibility - Provide clear focus indicator
UX Guidelines
- Threshold - Show after 200-400px scroll for optimal UX
- Positioning - Bottom-right is conventional, but avoid blocking content
- Animation Duration - 400-800ms provides smooth but quick scrolling
- Visual Clarity - Use clear up arrow (↑) or icon
Performance
- Throttle Scroll Events - Component automatically throttles scroll listeners
- Destroy When Done - Call
destroy()on single-page apps when navigating
API Reference
| Option | Type | Default | Description |
|---|---|---|---|
showAfter |
Number | 300 |
Scroll pixels before showing button |
duration |
Number | 500 |
Scroll animation duration (ms) |
position |
String | 'bottom-right' |
Position: bottom-right, bottom-left |
offset |
Object | { bottom: 20, right: 20 } |
Offset from edges (px) |
target |
String/Element | window |
Scroll target (default: window) |
onShow |
Function | null |
Show callback |
onHide |
Function | null |
Hide callback |
Methods
| Method | Parameters | Description |
|---|---|---|
scroll(duration) |
duration (optional) | Scroll to top with optional custom duration |
show() |
- | Show button immediately |
hide() |
- | Hide button immediately |
toggle() |
- | Toggle button visibility |
isVisible() |
- | Check if button is visible |
getButton() |
- | Get button element |
destroy() |
- | Remove button and clean up |
Config Engine
$.setup({
'#back-to-top': {
component: 'backToTop',
options: {
showAfter: 400,
duration: 600,
position: 'bottom-right',
onShow: () => console.log('Button appeared'),
onHide: () => console.log('Button hidden')
}
}
});
CSS Customisation
Override these CSS variables to customise Back-to-Top appearance and match your design system.
| Variable | Default | Controls |
|---|---|---|
--dm-primary | var(--dm-blue-600) | Button background colour |
--dm-primary-hover | var(--dm-blue-700) | Button hover colour |
--dm-radius-full | 9999px | Button shape (circular) |
--dm-shadow-md | 0 4px 6px... | Button shadow |
Example Override
:root {
/* Square button */
--dm-radius-full: 0.5rem;
}