A JavaScript library for smooth scrolling control in web applications.
- Smooth scrolling to specific positions or elements
- Support for both immediate and animated scrolling
- Auto-interrupt scrolling: automatically pauses when user manually scrolls up, and resumes when scrolled back to bottom
- TypeScript support with type definitions
- No external dependencies
- Works with any scrollable container
# npm
npm install smooth-scroll-controller
# pnpm
pnpm add smooth-scroll-controller
# yarn
yarn add smooth-scroll-controllerimport SmoothScrollController from "smooth-scroll-controller";
const scrollController = new SmoothScrollController({
container: document.getElementById("chat-messages"),
});
// Scroll to bottom
scrollController.settleDown();const SmoothScrollController = require("smooth-scroll-controller");
const scrollController = new SmoothScrollController({
container: document.getElementById("chat-messages"),
});new SmoothScrollController(options: ScrollControllerOptions)interface ScrollControllerOptions {
container: HTMLElement; // The scrollable container element
behavior?: "smooth" | "auto"; // Scroll behavior, default 'smooth'
duration?: number; // Animation duration in milliseconds, default 300
easing?: string; // Easing function, default 'ease-out'
}Smoothly scroll to the bottom of the container. This method is designed for continuous smooth scrolling when called multiple times in succession - each call will smoothly transition to the new bottom position, making it ideal for chat applications or live content feeds where new content is continuously added.
scrollController.settleDown();Scroll to a specific position.
scrollController.scrollTo(100);Scroll to a specific element.
const targetElement = document.getElementById("target");
scrollController.scrollToElement(targetElement);Immediately scroll to bottom without animation.
scrollController.scrollBottomImmediate();const chatContainer = document.getElementById("chat-messages");
const scrollController = new SmoothScrollController({
container: chatContainer,
});
// Auto-scroll when new message arrives
// Multiple rapid calls to settleDown() will create smooth continuous scrolling
function addMessage(message) {
const messageElement = createMessageElement(message);
chatContainer.appendChild(messageElement);
// Each call smoothly transitions to the new bottom position
scrollController.settleDown();
}
// Example: Adding multiple messages rapidly
function addMultipleMessages(messages) {
messages.forEach((message) => {
addMessage(message); // Each call will smoothly scroll down
});
}const contentContainer = document.getElementById("live-content");
const scrollController = new SmoothScrollController({
container: contentContainer,
duration: 500,
});
// Maintain scroll position during content updates
function updateContent(newContent) {
contentContainer.innerHTML = newContent;
scrollController.settleDown();
}pnpm install# Build the project
pnpm run build
# Watch for changes and rebuild
pnpm run start
# Run tests
pnpm run test
# Type checking
pnpm run typechecksmooth-scroll-controller/
├── src/ # Source code
├── dist/ # Build output
├── index.html # Demo page
├── package.json
├── tsconfig.json
└── README.md
Open the index.html file in your browser to see the demo. The demo includes:
- Real-time chat scrolling
- Markdown content rendering
- Streaming text output
- Responsive design
- Fork the repository
- Create a feature branch (
git checkout -b feature/new-feature) - Commit your changes (
git commit -m 'Add new feature') - Push to the branch (
git push origin feature/new-feature) - Create a Pull Request
- Initial release
- Basic scroll control functionality
- TypeScript support
This project is licensed under the MIT License.
Alex Reinforce
- GitHub: @alex-reinfoce
- Repository: https://github.com/alex-reinfoce/smooth-scroll-controller
Report bugs and feature requests at GitHub Issues.