# grsmto/simplebar architecture

> Architecture diagram of the GitHub repository grsmto/simplebar, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/grsmto/simplebar
- Repository: https://github.com/grsmto/simplebar

## Overview

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: [`packages/simplebar-core/src/index.ts`](https://github.com/grsmto/simplebar/blob/master/packages/simplebar-core/src/index.ts) (Core), [`lerna.json`](https://github.com/grsmto/simplebar/blob/master/lerna.json) (SimpleBar), [`packages/simplebar-vue/index.ts`](https://github.com/grsmto/simplebar/blob/master/packages/simplebar-vue/index.ts) (Vue), [`packages/simplebar/src/index.ts`](https://github.com/grsmto/simplebar/blob/master/packages/simplebar/src/index.ts) (SimpleBar)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace"]
  node_monorepo["SimpleBar<br/>workspace<br/>[lerna.json]"]
  node_buildtool["Rollup Build<br/>build tooling<br/>[rollup.config.mjs]"]
  node_coretests["Core Tests<br/>unit+e2e tests<br/>[simplebar.test.ts]"]
  node_reacttests["React Tests<br/>adapter tests<br/>[index.test.tsx]"]
  node_vuetests["Vue Tests<br/>adapter tests<br/>[index.test.ts]"]
  node_angulartests["Angular Tests<br/>adapter tests"]
end

subgraph group_runtime["Runtime"]
  node_core["Core<br/>scroll engine<br/>[index.ts]"]
  node_corecss["Core CSS<br/>stylesheet<br/>[simplebar.css]"]
  node_corehelpers["Helpers<br/>[helpers.ts]"]
  node_simplebar["SimpleBar<br/>vanilla package<br/>[index.ts]"]
end

subgraph group_adapters["Adapters"]
  node_react["React<br/>[index.tsx]"]
  node_vue["Vue<br/>[index.ts]"]
  node_angular["Angular"]
end

subgraph group_docs["Docs & Demos"]
  node_website["Website<br/>gatsby docs<br/>[gatsby-config.js]"]
  node_pkgexamples["Examples App<br/>demo app<br/>[index.js]"]
  node_exreact["React Demo<br/>example app<br/>[App.js]"]
  node_exvue2["Vue 2.7 Demo<br/>example app<br/>[App.vue]"]
  node_exvue3["Vue 3 Demo<br/>example app<br/>[App.vue]"]
  node_exangular["Angular Demo<br/>example app<br/>[app.component.ts]"]
  node_exjquery["jQuery Demo<br/>example app<br/>[index.html]"]
end

node_monorepo -->|"coordinates"| node_buildtool
node_monorepo -->|"contains"| node_core
node_monorepo -->|"contains"| node_simplebar
node_monorepo -->|"contains"| node_react
node_monorepo -->|"contains"| node_vue
node_monorepo -->|"contains"| node_angular
node_core -->|"styles"| node_corecss
node_core -->|"uses"| node_corehelpers
node_simplebar -->|"wraps"| node_core
node_react -->|"adapts"| node_core
node_vue -->|"adapts"| node_core
node_angular -->|"adapts"| node_core
node_website -->|"documents"| node_simplebar
node_website -->|"documents"| node_react
node_website -->|"documents"| node_vue
node_website -->|"documents"| node_angular
node_pkgexamples -->|"demonstrates"| node_simplebar
node_pkgexamples -->|"demonstrates"| node_core
node_exreact -->|"exercises"| node_react
node_exvue2 -->|"exercises"| node_vue
node_exvue3 -->|"exercises"| node_vue
node_exangular -->|"exercises"| node_angular
node_exjquery -->|"exercises"| node_simplebar
node_coretests -->|"verifies"| node_core
node_reacttests -->|"verifies"| node_react
node_vuetests -->|"verifies"| node_vue
node_angulartests -->|"verifies"| node_angular

click node_monorepo "https://github.com/grsmto/simplebar/blob/master/lerna.json"
click node_buildtool "https://github.com/grsmto/simplebar/blob/master/rollup.config.mjs"
click node_core "https://github.com/grsmto/simplebar/blob/master/packages/simplebar-core/src/index.ts"
click node_corecss "https://github.com/grsmto/simplebar/blob/master/packages/simplebar-core/src/simplebar.css"
click node_corehelpers "https://github.com/grsmto/simplebar/blob/master/packages/simplebar-core/src/helpers.ts"
click node_simplebar "https://github.com/grsmto/simplebar/blob/master/packages/simplebar/src/index.ts"
click node_react "https://github.com/grsmto/simplebar/blob/master/packages/simplebar-react/index.tsx"
click node_vue "https://github.com/grsmto/simplebar/blob/master/packages/simplebar-vue/index.ts"
click node_angular "https://github.com/grsmto/simplebar/blob/master/packages/simplebar-angular/src/lib/simplebar-angular.component.ts"
click node_website "https://github.com/grsmto/simplebar/blob/master/packages/website/gatsby-config.js"
click node_pkgexamples "https://github.com/grsmto/simplebar/blob/master/packages/examples/index.js"
click node_exreact "https://github.com/grsmto/simplebar/blob/master/examples/react/src/App.js"
click node_exvue2 "https://github.com/grsmto/simplebar/blob/master/examples/vue-2.7/src/App.vue"
click node_exvue3 "https://github.com/grsmto/simplebar/blob/master/examples/vue-3/src/App.vue"
click node_exangular "https://github.com/grsmto/simplebar/blob/master/examples/angular/src/app/app.component.ts"
click node_exjquery "https://github.com/grsmto/simplebar/blob/master/examples/jquery/index.html"
click node_coretests "https://github.com/grsmto/simplebar/blob/master/packages/simplebar-core/tests/simplebar.test.ts"
click node_reacttests "https://github.com/grsmto/simplebar/blob/master/packages/simplebar-react/tests/index.test.tsx"
click node_vuetests "https://github.com/grsmto/simplebar/blob/master/packages/simplebar-vue/tests/index.test.ts"
click node_angulartests "https://github.com/grsmto/simplebar/blob/master/packages/simplebar-angular/src/lib/simplebar-angular.component.spec.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_monorepo,node_buildtool,node_coretests,node_reacttests,node_vuetests,node_angulartests toneBlue
class node_core,node_corecss,node_corehelpers,node_simplebar toneAmber
class node_react,node_vue,node_angular toneMint
class node_website,node_pkgexamples,node_exreact,node_exvue2,node_exvue3,node_exangular,node_exjquery toneRose
```

## Components

### Workspace

Monorepo coordination and shared release/build tooling.

- [SimpleBar](https://github.com/grsmto/simplebar/blob/master/lerna.json): workspace · Lerna-managed monorepo for the cross-framework custom scrollbar library. · `lerna.json`
- [Rollup Build](https://github.com/grsmto/simplebar/blob/master/rollup.config.mjs): build tooling · Package-level bundling configuration used across distributable packages. · `rollup.config.mjs`
- [Core Tests](https://github.com/grsmto/simplebar/blob/master/packages/simplebar-core/tests/simplebar.test.ts): unit+e2e tests · Unit and browser tests that verify DOM behavior in real rendering conditions. · `packages/simplebar-core/tests/simplebar.test.ts`
- [React Tests](https://github.com/grsmto/simplebar/blob/master/packages/simplebar-react/tests/index.test.tsx): adapter tests · React-specific component tests and snapshots. · `packages/simplebar-react/tests/index.test.tsx`
- [Vue Tests](https://github.com/grsmto/simplebar/blob/master/packages/simplebar-vue/tests/index.test.ts): adapter tests · Vue wrapper tests and snapshots. · `packages/simplebar-vue/tests/index.test.ts`
- [Angular Tests](https://github.com/grsmto/simplebar/blob/master/packages/simplebar-angular/src/lib/simplebar-angular.component.spec.ts): adapter 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](https://github.com/grsmto/simplebar/blob/master/packages/simplebar-core/src/index.ts): scroll engine · DOM/CSS scrolling engine that measures native scroll state and renders custom scrollbar chrome. · `packages/simplebar-core/src/index.ts`
- [Core CSS](https://github.com/grsmto/simplebar/blob/master/packages/simplebar-core/src/simplebar.css): stylesheet · Default styling for the core scrollbar UI and wrapper structure. · `packages/simplebar-core/src/simplebar.css`
- [Helpers](https://github.com/grsmto/simplebar/blob/master/packages/simplebar-core/src/helpers.ts): DOM helpers · Shared utilities such as scrollbar width detection and DOM support logic. · `packages/simplebar-core/src/helpers.ts`
- [SimpleBar](https://github.com/grsmto/simplebar/blob/master/packages/simplebar/src/index.ts): vanilla package · 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](https://github.com/grsmto/simplebar/blob/master/packages/simplebar-react/index.tsx): react adapter · React wrapper that maps component lifecycle and refs onto the shared scrollbar engine. · `packages/simplebar-react/index.tsx`
- [Vue](https://github.com/grsmto/simplebar/blob/master/packages/simplebar-vue/index.ts): vue adapter · Vue wrapper that adapts the core scrollbar behavior to Vue component APIs. · `packages/simplebar-vue/index.ts`
- [Angular](https://github.com/grsmto/simplebar/blob/master/packages/simplebar-angular/src/lib/simplebar-angular.component.ts): angular adapter · 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](https://github.com/grsmto/simplebar/blob/master/packages/website/gatsby-config.js): gatsby docs · Public documentation and demo site for the library. · `packages/website/gatsby-config.js`
- [Examples App](https://github.com/grsmto/simplebar/blob/master/packages/examples/index.js): demo app · Shared playground/demo bundle used for hosted examples and project checks. · `packages/examples/index.js`
- [React Demo](https://github.com/grsmto/simplebar/blob/master/examples/react/src/App.js): example app · Standalone React example application for validating integration behavior. · `examples/react/src/App.js`
- [Vue 2.7 Demo](https://github.com/grsmto/simplebar/blob/master/examples/vue-2.7/src/App.vue): example app · Standalone Vue 2.7 example application. · `examples/vue-2.7/src/App.vue`
- [Vue 3 Demo](https://github.com/grsmto/simplebar/blob/master/examples/vue-3/src/App.vue): example app · Standalone Vue 3 example application. · `examples/vue-3/src/App.vue`
- [Angular Demo](https://github.com/grsmto/simplebar/blob/master/examples/angular/src/app/app.component.ts): example app · Standalone Angular example application. · `examples/angular/src/app/app.component.ts`
- [jQuery Demo](https://github.com/grsmto/simplebar/blob/master/examples/jquery/index.html): example app · Minimal HTML-based jQuery example. · `examples/jquery/index.html`

## Connections

- 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.
