Scrollito: Auto-scroll for Kavita

Adjustable, pausable auto-scrolling for Kavita's Webtoon reader.

An independent project. Not affiliated with, endorsed by, or part of the Kavita project.

The script adds a compact play/pause and speed control to Kavita manga-reader pages. It works as a userscript in modern browsers and can also be loaded as a temporary Safari Web Extension on macOS.

For extension-free clients—including an iPad Home Screen web app—the included Docker injector can place the same script into Kavita's HTML at the server.

Features

• Adjustable scrolling from 25 to 600 pixels per second
• Play/pause control suitable for mouse or touch
• Automatically hides the controls while scrolling and reveals them on input
• Can automatically start when Kavita enters Webtoon mode, and the Docker injector can turn auto-start or slip mode on by default
• Can be placed in any screen corner and remembers the selection
• Keyboard shortcuts can be remapped from the settings menu and are remembered per browser
• A hide button — in Scrollito's settings, in Kavita's own reader menu, or a keyboard shortcut — stops scrolling when you want to scroll manually and leaves nothing over the page
• Moves out of the way when Kavita's reader menu opens
• Pauses when you scroll, click, or touch outside the control
• On iPhone and iPad, holding a finger down to pause keeps iOS's save-image menu and text magnifier out of the way, and leaves Kavita's tap-to-open reader menu closed; all three behave normally again once scrolling stops
• Slip mode keeps the set pace through a manual scroll, so you can swipe ahead or back up a little without stopping
• Remembers the selected speed in the browser
• Handles Kavita's normal and fullscreen Webtoon readers
• Supports Kavita installations hosted at custom domains or base paths
• Makes no network requests and includes no analytics or telemetry

Install

The userscript/extension methods below run client-side: install on each browser or device you read from, and they work against any Kavita server you can open in that browser, including ones you don't administer. The Docker injector instead runs server-side: set it up once in front of your own Kavita instance and every client that visits it gets the script automatically, with no per-device install.

Safari on iPhone or iPad

1. Install the free Userscripts app.
2. Open Userscripts once so it creates its folder in Files.
3. In Settings > Apps > Safari > Extensions, enable Userscripts.
4. Download the raw userscript and save it in the folder selected by Userscripts.
5. Open your Kavita reader in Safari, allow Userscripts access to the website, and reload the page.

Safari on macOS

The Userscripts method above also works on macOS. For a temporary native Web Extension test instead:

1. Download or clone this repository.
2. In Safari Settings > Advanced, enable Show features for web developers.
3. In Settings > Developer, enable Allow unsigned extensions.
4. Click Add Temporary Extension… and select the repository folder.
5. Enable Scrollito, grant access to your Kavita website, and reload the reader.

Safari removes temporary extensions after 24 hours or when Safari quits.

Chrome, Firefox, Edge, and other desktop browsers

1. Install a userscript manager such as Tampermonkey or Violentmonkey.
2. Open the raw userscript.
3. Confirm installation, open a Kavita Webtoon, and reload the reader if it was already open.

Docker injector

The injector sits between your public reverse proxy and Kavita. It serves the script from the same origin and adds its script tag to Kavita's HTML, so no browser extension is required.

Build it locally from the repository root:

docker build \
  --file injector/Dockerfile \
  --build-arg AUTOSCROLL_VERSION=1.3.2 \
  --tag ghcr.io/nautxx/scrollito-injector:1.3.2 \
  .

See examples/docker-compose.yml for a full example. Point Caddy or your other public reverse proxy at the injector's port, not directly at Kavita. KAVITA_UPSTREAM may be changed when your Kavita service uses another Compose hostname or port. The example includes a local build definition; remove its build block if you only want to pull the published GHCR image. The injector also reads these optional values from the Compose environment:

• AUTOSCROLL_TOGGLE_SHORTCUT (default s)
• AUTOSCROLL_SLOWER_SHORTCUT (default [)
• AUTOSCROLL_FASTER_SHORTCUT (default ])
• AUTOSCROLL_HIDE_SHORTCUT (default a)
• AUTOSCROLL_SPEED_STEP (default 25 pixels per second)
• AUTOSCROLL_AUTO_START (default false)
• AUTOSCROLL_SLIP_MODE (default false)

Set them in the Compose .env file and recreate the injector container. Values use the browser's KeyboardEvent.key names, such as Space, ArrowDown, or a single printable character. Avoid double quotes and HTML-special characters in shortcut values. AUTOSCROLL_SPEED_STEP must be a positive number and controls both the keyboard increment and slider step.

AUTOSCROLL_AUTO_START and AUTOSCROLL_SLIP_MODE accept true or false and decide how those two toggles start out for a reader who has not touched them. They are defaults, not policies: once someone flips either toggle, that browser keeps their choice and ignores the configured value.

Keybindings

Put the exact key name in the Compose .env file. Common values are:

Physical key	.env value
Enter	Enter
Spacebar	Space
Up arrow	ArrowUp
Down arrow	ArrowDown
Left arrow	ArrowLeft
Right arrow	ArrowRight
Letter S	s
Left bracket	[
Right bracket	]

For example, this uses Enter to toggle scrolling and the arrow keys to adjust the speed by 10 pixels per second:

AUTOSCROLL_TOGGLE_SHORTCUT=Enter
AUTOSCROLL_SLOWER_SHORTCUT=ArrowDown
AUTOSCROLL_FASTER_SHORTCUT=ArrowUp
AUTOSCROLL_SPEED_STEP=10
AUTOSCROLL_AUTO_START=true
AUTOSCROLL_SLIP_MODE=true

Key names are case-insensitive. Each binding must be one key; combinations using Control, Command, or Alt are intentionally ignored. Recreate the injector container after editing .env.

Usage

• Select the play icon to begin and the pause icon to stop.
• Move the slider to change speed.
• Select the settings (sliders) icon to open settings. From there, move the controls to any corner or enable Auto-start in Webtoon mode.
• Press S to toggle scrolling on a hardware keyboard.
• Press [ or ] to decrease or increase speed.
• Select the eye icon in settings or at the left of Kavita's reader menu, or press A, to hide the control and stop scrolling, such as when you want to scroll manually. Nothing is left over the page — select the eye in Kavita's menu again, or press A, to bring the control back. That icon stays in the menu whether the control is showing or hidden, so Kavita's own icons never shift. On a Kavita whose menu layout is not recognized, a small tab stays in the corner instead.
• In settings, select the keyboard icon to remap shortcuts. Select a key (S, [, ], or A) and press any key to reassign it, or Escape to cancel. Remapped shortcuts are remembered in that browser and take priority over the Docker injector's configured keys.
• In settings, select the up-and-down arrows icon to turn on slip mode. Scrolling then seeks instead of stopping: swipe ahead, swipe back, or spin the wheel, and auto-scroll carries on at the set speed from wherever you land. It holds still while a finger is down and picks up again when you lift it. Use the pause icon or S to stop while slip mode is on.
• Scrolling, clicking, or touching outside the control pauses auto-scroll, unless slip mode is on.
• While auto-scroll is running, the controls fade away after 2.5 seconds of inactivity. Move the pointer, touch the page, or use the keyboard to reveal them. The controls remain visible while paused.

Kavita must be using its Webtoon reader mode. The controls appear only when Kavita's infinite scroller is active, including when a reading profile or Automatic Webtoon Reader Mode selects it. If you install the script while a reader is already open, reload that page once.

Permissions and privacy

Self-hosted Kavita instances can use any hostname, so the script matches HTTP(S) pages whose path contains /manga/. It does nothing beyond those matched pages.

The script does not read credentials, call Kavita APIs, send data, or load remote code. Its only stored values are the scrolling speed, preferred control corner, auto-start and slip-mode preferences, and any remapped keyboard shortcuts, all in that site's local browser storage. Review the complete source in scrollito.user.js.

Browser support

The Safari scroll behavior is tested on macOS. The userscript uses standard web APIs and is designed for current Safari, Chrome, Firefox, Edge, and compatible userscript managers. iPhone and iPad installation is supported through Userscripts, but device and Kavita-version differences may require testing.

Contributing

Bug reports and pull requests are welcome. When reporting a problem, include your browser, operating system, Kavita version, whether fullscreen was enabled, and the reader URL with private hostnames or identifiers removed.

Local UI preview

Run the dependency-free preview from the repository root:

./scripts/preview.sh

Open the URL printed in the terminal. The script starts at port 8080 and automatically tries the next port if it is already occupied. The page loads the working copy of scrollito.user.js, mocks Kavita's Webtoon reader and animated menus, and reloads automatically after either preview source changes. Use the on-page buttons or press M to toggle the reader menu and X to expand its settings area.

Packaging a release

Run:

./scripts/package.sh 1.3.2

This creates a userscript, a WebExtension ZIP, and SHA256SUMS.txt under the versioned build/release/v1.3.2/ directory. The injector image uses the userscript at the repository root as its source, so the browser and server packages stay on the same version.

Pushing a matching tag such as v1.3.2 runs the release workflow. It publishes the assets as a GitHub release and builds linux/amd64 and linux/arm64 injector images in GitHub Container Registry.

License

MIT

The control's icons are from Font Awesome Free 7.3.1 and are licensed CC BY 4.0. They are embedded as inline SVG paths rather than loaded as a font, so the script stays a single file with no network requests. Kavita's own UI ships the same icon set.