# mukiturrahman/locomotive-scroll architecture

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

- Interactive diagram: https://gitdiagram.com/mukiturrahman/locomotive-scroll
- Repository: https://github.com/mukiturrahman/locomotive-scroll

## Overview

1. **What this repo is**
   - This is a browser-side JavaScript library, not an application backend.
   - Its core product is a scroll controller that combines viewport detection, smooth scrolling, parallax, sticky behavior, and programmatic scrolling.

2. **Public package boundary**
   - The main entry points are in `src/locomotive-scroll.js` and the built artifacts in `dist/`.
   - Consumers import the library as ES module or UMD, and optionally include the generated stylesheet `dist/locomotive-scroll.css`.

3. **Runtime architecture**
   - The source is split into a shared core plus mode-specific implementations.
   - `Core.js` appears to hold common lifecycle and element-tracking behavior.
   - `Main.js` and `NativeMain.js` likely represent the top-level orchestration for smooth vs native scrolling modes.
   - `Smooth.js` and `Native.js` split the actual scroll mechanics by mode.

4. **Scroll modes and control flow**
   - In **native mode**, the library observes normal browser scrolling and focuses on element detection and events.
   - In **smooth mode**, it intercepts scroll input, applies inertia/lerp, and manages a virtual scroll position.
   - The mode choice is driven by instance options such as `smooth`, `direction`, `lerp`, `gestureDirection`, and device-specific overrides.

5. **Element detection and in-view state**
   - The library scans DOM elements marked with `data-scroll` and related attributes.
   - It computes viewport intersection, progress, offsets, and repeat behavior.
   - Current in-view elements are exposed through the `scroll` event payload, and `data-scroll-call` triggers custom callbacks/events.

6. **Parallax, sticky, and motion features**
   - Smooth mode adds animation-like behavior through attributes such as `data-scroll-speed`, `data-scroll-delay`, `data-scroll-direction`, `data-scroll-sticky`, and `data-scroll-target`.
   - These features depend on transform calculations rather than layout reflow, which is why utilities like `transform.js` matter to the architecture.

7. **Shared utilities and configuration**
   - `options.js` centralizes default option handling and likely normalizes user configuration.
   - `utils/html.js`, `utils/maths.js`, and `utils/transform.js` provide DOM, math, and transform helpers used across the scroll implementations.

8. **Event model**
   - The library exposes instance events such as `scroll` and `call`.
   - That event surface is the main integration boundary for app code: animation libraries, UI state updates, analytics, or custom routing logic subscribe there rather than coupling directly to internals.

9. **Styling subsystem**
   - The scroll behavior depends on stylesheet support in `src/locomotive-scroll.scss` and `src/styles/_base.scss`, plus scrollbar styles in `_scrollbar.scss`.
   - These styles define the structural classes and container behavior required for the scrolling container and custom scrollbar in smooth mode.

10. **Build and packaging pipeline**
   - The repo uses a Gulp-based build system in `gulpfile.babel.js` and the `build/` scripts to compile, bundle, copy, serve, watch, and notify.
   - Tooling includes Babel and Sass, with browser targeting defined by `.browserslistrc` and style formatting governed by `.prettierrc`.
   - The release outputs are placed in `dist/` as distributable JS/CSS bundles.

11. **Docs/demo site as a separate front-end**
   - `docs/` is a standalone demo/documentation site with its own source tree under `docs/src/` and compiled assets in `docs/dist/`.
   - It has separate scripts, styles, images, and HTML entry pages like `docs/index.html` and `docs/horizontal.html`, so the demo is architecturally distinct from the library itself.

12. **External dependencies that shape architecture**
   - The scroll engine relies on `virtual-scroll` for momentum-like input handling, `bezier-easing` for animated `scrollTo`, and a viewport-detection approach derived from `modularScroll`.
   - These dependencies reinforce that the library is entirely client-side and focused on DOM input/output, not data fetching or server interaction.

Main entry points: [`src/scripts/Core.js`](https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/scripts/Core.js) (Core), [`src/scripts/Smooth.js`](https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/scripts/Smooth.js) (Smooth), [`src/locomotive-scroll.js`](https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/locomotive-scroll.js) (Public API), [`src/locomotive-scroll.scss`](https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/locomotive-scroll.scss) (SCSS Entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_library["Library"]
  node_entry["Public API<br/>package entry"]
  node_core["Core<br/>shared runtime<br/>[Core.js]"]
  node_main["Main<br/>smooth orchestrator<br/>[Main.js]"]
  node_nativemain["Native Main<br/>native orchestrator<br/>[NativeMain.js]"]
  node_smooth["Smooth<br/>[Smooth.js]"]
  node_native["Native<br/>[Native.js]"]
  node_options["Options<br/>config normalization<br/>[options.js]"]
  node_htmlutil["HTML Utils<br/>dom helpers<br/>[html.js]"]
  node_mathsutil["Math Utils<br/>math helpers<br/>[maths.js]"]
  node_transformutil["Transform Utils<br/>motion helpers<br/>[transform.js]"]
end

subgraph group_styles["Styles"]
  node_publiccss["Public CSS<br/>distributed stylesheet"]
  node_basecss["Base Styles<br/>scss base<br/>[_base.scss]"]
  node_scrollbarcss["Scrollbar Styles<br/>scss component<br/>[_scrollbar.scss]"]
  node_scssentry["SCSS Entry<br/>style entry"]
end

subgraph group_tooling["Tooling"]
  node_build["Build System<br/>gulp pipeline<br/>[gulpfile.babel.js]"]
  node_scriptsbuild["Build Scripts<br/>task modules<br/>[scripts.js]"]
end

subgraph group_docs["Docs Demo"]
  node_docsapp["Docs Site<br/>demo frontend<br/>[index.html]"]
  node_docscripts["Docs JS<br/>demo runtime<br/>[main.js]"]
  node_docsstyles["Docs Styles<br/>demo styles<br/>[main.scss]"]
end

node_entry -->|"exports"| node_core
node_entry -->|"smooth mode"| node_main
node_entry -->|"native mode"| node_nativemain
node_main -->|"uses"| node_smooth
node_nativemain -->|"uses"| node_native
node_core -->|"config"| node_options
node_core -->|"dom"| node_htmlutil
node_core -->|"math"| node_mathsutil
node_smooth -->|"motion"| node_transformutil
node_smooth -->|"compute"| node_mathsutil
node_smooth -->|"scan"| node_htmlutil
node_native -->|"observe"| node_htmlutil
node_native -->|"compute"| node_mathsutil
node_scssentry -->|"includes"| node_basecss
node_scssentry -->|"includes"| node_scrollbarcss
node_scssentry -->|"builds"| node_publiccss
node_build -->|"orchestrates"| node_scriptsbuild
node_scriptsbuild -->|"bundles"| node_entry
node_scriptsbuild -->|"compiles"| node_scssentry
node_build -->|"serves"| node_docsapp
node_docsapp -->|"runs"| node_docscripts
node_docsapp -->|"styles"| node_docsstyles

click node_entry "https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/locomotive-scroll.js"
click node_core "https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/scripts/Core.js"
click node_main "https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/scripts/Main.js"
click node_nativemain "https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/scripts/NativeMain.js"
click node_smooth "https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/scripts/Smooth.js"
click node_native "https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/scripts/Native.js"
click node_options "https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/scripts/options.js"
click node_htmlutil "https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/scripts/utils/html.js"
click node_mathsutil "https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/scripts/utils/maths.js"
click node_transformutil "https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/scripts/utils/transform.js"
click node_publiccss "https://github.com/mukiturrahman/locomotive-scroll/blob/master/dist/locomotive-scroll.css"
click node_basecss "https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/styles/_base.scss"
click node_scrollbarcss "https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/styles/_scrollbar.scss"
click node_scssentry "https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/locomotive-scroll.scss"
click node_build "https://github.com/mukiturrahman/locomotive-scroll/blob/master/gulpfile.babel.js"
click node_scriptsbuild "https://github.com/mukiturrahman/locomotive-scroll/blob/master/build/scripts.js"
click node_docsapp "https://github.com/mukiturrahman/locomotive-scroll/blob/master/docs/index.html"
click node_docscripts "https://github.com/mukiturrahman/locomotive-scroll/blob/master/docs/src/scripts/main.js"
click node_docsstyles "https://github.com/mukiturrahman/locomotive-scroll/blob/master/docs/src/styles/main.scss"

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_entry,node_core,node_main,node_nativemain,node_smooth,node_native,node_options,node_htmlutil,node_mathsutil,node_transformutil toneBlue
class node_publiccss,node_basecss,node_scrollbarcss,node_scssentry toneAmber
class node_build,node_scriptsbuild toneMint
class node_docsapp,node_docscripts,node_docsstyles toneRose
```

## Components

### Library

Core browser-side scroll controller and public package entry points

- [Public API](https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/locomotive-scroll.js): package entry · ESM/UMD entry points and distributable assets for consumers · `src/locomotive-scroll.js`
- [Core](https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/scripts/Core.js): shared runtime · Common lifecycle, element tracking, and scroll state behavior · `src/scripts/Core.js`
- [Main](https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/scripts/Main.js): smooth orchestrator · Top-level coordination for smooth scrolling mode · `src/scripts/Main.js`
- [Native Main](https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/scripts/NativeMain.js): native orchestrator · Top-level coordination for native scrolling mode · `src/scripts/NativeMain.js`
- [Smooth](https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/scripts/Smooth.js): smooth engine · Virtual scrolling, inertia, parallax, sticky, and transformed motion · `src/scripts/Smooth.js`
- [Native](https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/scripts/Native.js): native engine · Browser scroll observation and in-view detection in native mode · `src/scripts/Native.js`
- [Options](https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/scripts/options.js): config normalization · Default options and device-specific configuration handling · `src/scripts/options.js`
- [HTML Utils](https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/scripts/utils/html.js): dom helpers · DOM and element helper functions shared by scroll modes · `src/scripts/utils/html.js`
- [Math Utils](https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/scripts/utils/maths.js): math helpers · Numeric helpers for offsets, progress, and interpolation · `src/scripts/utils/maths.js`
- [Transform Utils](https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/scripts/utils/transform.js): motion helpers · Transform calculations used for parallax and sticky motion · `src/scripts/utils/transform.js`

### Styles

SCSS source and generated CSS for scroll container and scrollbar

- [Public CSS](https://github.com/mukiturrahman/locomotive-scroll/blob/master/dist/locomotive-scroll.css): distributed stylesheet · Generated stylesheet consumed alongside the JavaScript bundle · `dist/locomotive-scroll.css`
- [Base Styles](https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/styles/_base.scss): scss base · Core structural styles for the scrolling container · `src/styles/_base.scss`
- [Scrollbar Styles](https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/styles/_scrollbar.scss): scss component · Custom scrollbar styles used by smooth scrolling mode · `src/styles/_scrollbar.scss`
- [SCSS Entry](https://github.com/mukiturrahman/locomotive-scroll/blob/master/src/locomotive-scroll.scss): style entry · Primary stylesheet entry that assembles the library styles · `src/locomotive-scroll.scss`

### Tooling

Build, bundling, and release pipeline

- [Build System](https://github.com/mukiturrahman/locomotive-scroll/blob/master/gulpfile.babel.js): gulp pipeline · Compilation, bundling, copying, serving, watching, and notifications · `gulpfile.babel.js`
- [Build Scripts](https://github.com/mukiturrahman/locomotive-scroll/blob/master/build/scripts.js): task modules · Individual build tasks for scripts, styles, assets, and dev workflow · `build/scripts.js`

### Docs Demo

Standalone documentation and demo site

- [Docs Site](https://github.com/mukiturrahman/locomotive-scroll/blob/master/docs/index.html): demo frontend · Standalone documentation and demo application · `docs/index.html`
- [Docs JS](https://github.com/mukiturrahman/locomotive-scroll/blob/master/docs/src/scripts/main.js): demo runtime · Demo-site behavior and examples rendered in the docs frontend · `docs/src/scripts/main.js`
- [Docs Styles](https://github.com/mukiturrahman/locomotive-scroll/blob/master/docs/src/styles/main.scss): demo styles · Docs site styling and layout system · `docs/src/styles/main.scss`

## Connections

- Public API → Core: exports · Public bundle exposes the shared scroll runtime
- Public API → Main: smooth mode · Entry selects the smooth-mode orchestration path
- Public API → Native Main: native mode · Entry selects the native-mode orchestration path
- Main → Smooth: uses · Smooth orchestration delegates to the smooth engine
- Native Main → Native: uses · Native orchestration delegates to the native engine
- Core → Options: config · Core behavior is driven by normalized options
- Core → HTML Utils: dom · Common runtime relies on DOM helpers
- Core → Math Utils: math · Shared state computations use numeric helpers
- Smooth → Transform Utils: motion · Smooth mode uses transform calculations for parallax and sticky effects
- Smooth → Math Utils: compute · Smooth mode computes offsets, interpolation, and progress
- Smooth → HTML Utils: scan · Smooth mode scans and manages scroll elements in the DOM
- Native → HTML Utils: observe · Native mode tracks elements and viewport state in the DOM
- Native → Math Utils: compute · Native mode computes visibility, offsets, and progress
- SCSS Entry → Base Styles: includes · Library stylesheet assembles base structural rules
- SCSS Entry → Scrollbar Styles: includes · Library stylesheet assembles smooth-mode scrollbar rules
- SCSS Entry → Public CSS: builds · SCSS source is compiled into the distributable CSS bundle
- Build System → Build Scripts: orchestrates · Gulp task runner coordinates build steps
- Build Scripts → Public API: bundles · Build pipeline produces distributable JavaScript bundles
- Build Scripts → SCSS Entry: compiles · Build pipeline compiles source SCSS into CSS output
- Build System → Docs Site: serves · Build tooling supports the docs/demo site workflow
- Docs Site → Docs JS: runs · Demo site behavior is implemented in its own script entry
- Docs Site → Docs Styles: styles · Demo site uses its own stylesheet tree