How grsmto/simplebar works
This repository is a monorepo for SimpleBar, a cross-framework custom scrollbar library. The central architectural idea is strict: it does not replace native scrolling. Instead, it keeps overflow: auto and overlays custom scrollbar visuals, which preserves browser scrolling behavior and performance.
1. Core scrolling engine
- packages/simplebar-core is the main implementation.
- It contains the DOM/CSS logic that measures content, tracks native scroll position, and renders the custom scrollbar UI.
- The core package ships its own stylesheet (src/simplebar.css) and helper code for things like scrollbar width detection.
2. Framework-agnostic public API
- packages/simplebar is the plain JavaScript package that exposes the core functionality for non-framework consumers.
- This is the base distribution most users import directly when they want SimpleBar without React/Vue/Angular bindings.
3. Framework wrappers as thin adapters
- packages/simplebar-react, packages/simplebar-vue, and packages/simplebar-angular are not alternate implementations; they are adapters around the same scrollbar engine.
- Their job is to fit SimpleBar into each framework’s lifecycle, templating, and ref/component model while delegating the actual scrolling behavior to the core.
4. Data flow from host element to scrollbar UI
- A consumer attaches SimpleBar to a scrollable container.
- The library wraps the host content with internal DOM structure, observes the scroll container, and updates scrollbar thumb size/position based on native scroll metrics.
- The important boundary is that scrolling remains browser-native; the library only synchronizes and styles the visual chrome.
5. Distribution and bundling
- The repo uses rollup.config.mjs in multiple packages, indicating package-level bundling for library distribution.
- TypeScript is used heavily in the core and Angular packages; Babel is used where framework/package build pipelines need it.
- lerna.json shows this is managed as a multi-package workspace with coordinated versioning/builds.
6. Documentation and product site
- packages/website is the Gatsby-based documentation/demo site.
- It serves as the public-facing hub for docs, examples, and interactive playgrounds rather than being part of the runtime library itself.
- This is a separate deployment boundary from the packages consumers install.
7. Examples and demo applications
- The top-level examples/ folder contains framework-specific demo apps for Angular, React, Vue 2.7, Vue 3, and a jQuery example.
- packages/examples appears to be the main demo/test playground used for the project’s hosted examples page and automated checks.
- These apps validate that the same core behavior works consistently across ecosystems.
8. Testing strategy
- Each package has its own unit tests, and the core package also includes end-to-end browser tests.
- packages/simplebar-core has both Jest unit and Puppeteer-based E2E configurations, reflecting the fact that scrollbar behavior must be verified in a real browser DOM.
- Angular, React, and Vue packages each have their own test setup, showing framework-specific adapter verification.
9. Browser/DOM-centric dependency boundary
- This is a UI component library with a strong dependency on browser layout and scrolling APIs.
- The architecture is therefore centered on DOM measurement, CSS styling, and cross-browser compatibility rather than on backend services or data persistence.
10. Release and CI/tooling
- The repository includes Travis CI configuration, package-specific test runners, and formatting/linting configs (.eslintrc.json, .prettierrc, .editorconfig).
- CHANGELOG.md files per package indicate the repo is released as multiple consumable artifacts, not a single app.
11. How to think about the overall diagram
- At the center is simplebar-core.
- Surrounding it are thin framework adapters and the vanilla package.
- External edges are the docs site and example apps, which depend on the packages but do not feed runtime behavior back into them.
- Tests span the core and wrappers, using browser automation where behavior depends on real rendering.
12. Key architectural boundary
- The most important boundary to capture is: native scrolling remains inside the browser, while SimpleBar owns only the wrapper structure and scrollbar presentation.
- Everything else in the repo—framework packages, demos, docs, and tests—exists to package, present, or validate that one core behavior across environments.
Main entry points: src/index.ts Core · lerna.json SimpleBar · simplebar-vue/index.ts Vue · src/index.ts SimpleBar
Components 20
Workspace
Monorepo coordination and shared release/build tooling.
- SimpleBar · Lerna-managed monorepo for the cross-framework custom scrollbar library.
lerna.json - Rollup Build · Package-level bundling configuration used across distributable packages.
rollup.config.mjs - Core Tests · Unit and browser tests that verify DOM behavior in real rendering conditions.
packages/simplebar-core/tests/simplebar.test.ts - React Tests · React-specific component tests and snapshots.
packages/simplebar-react/tests/index.test.tsx - Vue Tests · Vue wrapper tests and snapshots.
packages/simplebar-vue/tests/index.test.ts - Angular Tests · Angular component spec tests.
packages/simplebar-angular/src/lib/simplebar-angular.component.spec.ts
Runtime
Library packages that implement scrolling behavior and public APIs.
- Core · DOM/CSS scrolling engine that measures native scroll state and renders custom scrollbar chrome.
packages/simplebar-core/src/index.ts - Core CSS · Default styling for the core scrollbar UI and wrapper structure.
packages/simplebar-core/src/simplebar.css - Helpers · Shared utilities such as scrollbar width detection and DOM support logic.
packages/simplebar-core/src/helpers.ts - SimpleBar · Framework-agnostic JavaScript entry point built on top of the core engine.
packages/simplebar/src/index.ts
Adapters
Framework-specific wrappers around the shared scrolling engine.
- React · React wrapper that maps component lifecycle and refs onto the shared scrollbar engine.
packages/simplebar-react/index.tsx - Vue · Vue wrapper that adapts the core scrollbar behavior to Vue component APIs.
packages/simplebar-vue/index.ts - Angular · Angular wrapper package built around the same scrolling engine.
packages/simplebar-angular/src/lib/simplebar-angular.component.ts
Docs & Demos
Public site and example applications used to showcase and validate behavior.
- Website · Public documentation and demo site for the library.
packages/website/gatsby-config.js - Examples App · Shared playground/demo bundle used for hosted examples and project checks.
packages/examples/index.js - React Demo · Standalone React example application for validating integration behavior.
examples/react/src/App.js - Vue 2.7 Demo · Standalone Vue 2.7 example application.
examples/vue-2.7/src/App.vue - Vue 3 Demo · Standalone Vue 3 example application.
examples/vue-3/src/App.vue - Angular Demo · Standalone Angular example application.
examples/angular/src/app/app.component.ts - jQuery Demo · Minimal HTML-based jQuery example.
examples/jquery/index.html
Connections 27
- SimpleBar → Rollup Build: coordinates · Workspace-level release and bundling coordination.
- SimpleBar → Core: contains · Primary runtime package in the monorepo.
- SimpleBar → SimpleBar: contains · Vanilla consumer package in the monorepo.
- SimpleBar → React: contains · React adapter package.
- SimpleBar → Vue: contains · Vue adapter package.
- SimpleBar → Angular: contains · Angular adapter package.
- Core → Core CSS: styles · Core engine ships and applies its own scrollbar stylesheet.
- Core → Helpers: uses · Core engine relies on shared DOM utilities.
- SimpleBar → Core: wraps · Vanilla API exposes the shared scrolling engine.
- React → Core: adapts · React layer delegates scroll behavior to the core implementation.
- Vue → Core: adapts · Vue layer delegates scroll behavior to the core implementation.
- Angular → Core: adapts · Angular layer delegates scroll behavior to the core implementation.
- Website → SimpleBar: documents · Docs site explains and demos the vanilla package.
- Website → React: documents · Docs site includes framework wrapper guidance.
- Website → Vue: documents · Docs site includes framework wrapper guidance.
- Website → Angular: documents · Docs site includes framework wrapper guidance.
- Examples App → SimpleBar: demonstrates · Shared demo bundle exercises the vanilla package.
- Examples App → Core: demonstrates · Playground covers the shared engine behavior.
- React Demo → React: exercises · React example validates the wrapper in a real app.
- Vue 2.7 Demo → Vue: exercises · Vue 2.7 example validates the wrapper in a real app.
- Vue 3 Demo → Vue: exercises · Vue 3 example validates the wrapper in a real app.
- Angular Demo → Angular: exercises · Angular example validates the wrapper in a real app.
- jQuery Demo → SimpleBar: exercises · jQuery example validates the vanilla integration path.
- Core Tests → Core: verifies · Browser and unit tests verify the core scroll engine.
- React Tests → React: verifies · Component tests verify the React adapter.
- Vue Tests → Vue: verifies · Component tests verify the Vue adapter.
- Angular Tests → Angular: verifies · Spec tests verify the Angular adapter.