canvas-scrollbar

A lightweight, customizable scrollbar implementation for HTML Canvas elements. This library provides an efficient way to add scrolling capabilities to canvas-based applications.

应用于 Canvas 的自定义滚动条组件，支持水平和垂直方向滚动，可自定义样式和交互行为。

Features

• 🚥 Scrolling horizontally and vertically
• 💄 Customizable appearance
• ⏰ Support mouse and wheel events
• 🚀 No dependencies

Installation

npm

npm install canvas-scrollbar

browser

https://cdn.jsdelivr.net/npm/canvas-scrollbar/dist/index.min.js

Usage

const canvas = document.getElementById('myCanvas')
const scrollbar = new CanvasScrollbar(canvas, {
	direction: 'y', // 'y' for vertical, 'x' for horizontal
	contentSize: 1000, // Total content height/width
	viewportSize: canvas.height, // Visible area size
	onscroll: (position, maxScroll) => {
		// Handle scroll position changes
		console.log('Scrolled to:', position)
	},
})

[!TIP]

Vertical scrollbar defaults to right side.
Horizontal scrollbar defaults to bottom side.

API

Constructor

new CanvasScrollbar(canvas, options)

Parameters

• canvas (HTMLCanvasElement): The canvas element to attach the scrollbar to
• options (Object): Configuration options

Options

| Option | Type | Default | Description | | -------------- | -------- | ------------------ | -------------------------------------------------------------- | | x | number | - | Scrollbar's left position | | y | number | - | Scrollbar's top position | | width | number | - | Scrollbar's width | | height | number | - | Scrollbar's height | | direction | string | 'y' | Scroll direction: 'x' or 'y' | | contentSize | number | 0 | Total content size (width for horizontal, height for vertical) | | viewportSize | number | Canvas dimension | Visible area size | | style | object | See below | Scrollbar styling options | | onscroll | function | (pos, max) => {} | Callback when scroll position changes |

Style Options

| Option | Type | Default | Description | | ----------------- | ------ | ------- | ---------------------------------- | | color | string | '#000' | Scrollbar thumb color | | backgroundColor | string | '#fff' | Scrollbar track color | | radius | number | 0 | Scrollbar corner radius | | padding | number | 0 | Padding inside the scrollbar track |

Methods

draw()

Draws the scrollbar on the canvas.

scrollbar.draw()

scroll(delta)

Scrolls by the specified amount.

// Scroll down 50 pixels
scrollbar.scroll(50)

scrollTo(position)

Scrolls to a specific position.

// Scroll to position 200
scrollbar.scrollTo(200)

update(contentSize, viewportSize)

Updates the content and viewport dimensions.

// Update when content changes
scrollbar.update(newContentSize, newViewportSize)

destroy()

Removes event listeners and cleans up resources.

scrollbar.destroy()

Examples

const canvas = document.getElementById('myCanvas')
const ctx = canvas.getContext('2d')

// Content to be scrolled
const content = {
	height: 2000,
	render: function (pos) {
		// Clear canvas
		ctx.clearRect(0, 0, canvas.width, canvas.height)

		ctx.save()
		ctx.translate(0, -pos)

		ctx.fillStyle = '#007bff'
		for (let y = 0; y < content.height; y += 100) {
			for (let x = 0; x < canvas.width; x += 100) {
				ctx.fillRect(x + 10, y + 10, 80, 80)
			}
		}

		ctx.restore()
	},
}

// Create scrollbar
const scrollbar = new CanvasScrollbar(canvas, {
	direction: 'y',
	contentSize: content.height,
	style: {
		color: '#555',
		backgroundColor: '#eee',
		radius: 5,
		padding: 2,
	},
	onscroll: (position) => {
		// Redraw content at new scroll position
		content.render(position)
	},
})

// Initial render
content.render(0)
scrollbar.draw()

License

MIT © Mariner

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.