rc-virtual-canvas
Scrollable virtual canvas for rendering large coordinate-space content.
Overlays a transparent scrollable div on top of a slotted <canvas> element,
dispatching rc-virtual-canvas-render events with the current viewport and
content rectangles. Consumers draw only what is visible.
- Package
@rcarls/rc-virtual-canvas- Element
<rc-virtual-canvas>- Native dependency
- Canvas and overlay content
- State model
- Virtual scroll geometry
- Main events
rc-virtual-canvas-pointerrc-virtual-canvas-render- Related
- Theme previews
Installation
- npm
- Yarn
npm install @rcarls/rc-virtual-canvas
yarn add @rcarls/rc-virtual-canvas
import '@rcarls/rc-virtual-canvas/define';
Live demo
Theming
The default demo mode shows the component without a package theme. Use the shared preview controls on this page to compare inherited, light, and dark color schemes or to apply the optional Material theme only inside the demo frames.
API
Properties
| Property | Markup | Type | Default | Description |
|---|---|---|---|---|
contentWidth | contentWidth | Unknown | Not specified | Pixel width of the virtual content |
contentHeight | contentHeight | Unknown | Not specified | Pixel height of the virtual content |
autoResizeCanvas | auto-resize-canvas | boolean | true | When true, keep the slotted canvas backing store aligned to the viewport. |
renderMode | render-mode | RCVirtualCanvasRenderMode | 'continuous' | Controls when render events are dispatched. |
imageRendering | image-rendering | RCVirtualCanvasImageRendering | 'auto' | Convenience image-rendering value applied to the slotted canvas. |
canvasScaleX | JS property only | number | Not specified | Ratio of canvas backing-store pixels to CSS pixels along the x-axis. Equals `devicePixelRatio` when `autoResizeCanvas` is `true`. Use as the x-scale factor in `ctx.scale()` to draw at CSS pixel resolution. |
canvasScaleY | JS property only | number | Not specified | Ratio of canvas backing-store pixels to CSS pixels along the y-axis. Equals `devicePixelRatio` when `autoResizeCanvas` is `true`. Use as the y-scale factor in `ctx.scale()` to draw at CSS pixel resolution. |
Methods
| Method | Description |
|---|---|
getViewRect() | Returns a frozen snapshot of the current viewport rectangle. Safe to keep between frames — the returned object will not be mutated by future scroll or resize work. |
scrollToContent(x: number, y: number, options: ScrollOptions) | Scrolls so the content coordinate is at the viewport origin. |
centerOnContent(x: number, y: number, options: ScrollOptions) | Scrolls so the content coordinate is centered in the viewport. |
clientToContent(clientX: number, clientY: number) | Converts browser client coordinates to content coordinates using the current backing-store scale. |
contentToClient(x: number, y: number) | Converts content coordinates back to browser client coordinates. |
requestRender(reason: RCVirtualCanvasRenderReason) | Queues a render event on the next animation frame. Required when `renderMode` is `'manual'`. In other modes the component schedules renders automatically; calling this with reason `'animation-frame'` is a no-op when `renderMode` is `'viewport-change'`. |
Events
| Event | Detail type | Description |
|---|---|---|
rc-virtual-canvas-pointer | CustomEvent | Fires pointer/mouse input mapped to virtual content coordinates. |
rc-virtual-canvas-render | CustomEvent | Fires with viewport data when the canvas should redraw. |
Slots
| Name | Description |
|---|---|
(default) | The HTMLCanvasElement |
overlay | Optional viewport-positioned content rendered inside the scroll container above the canvas. |
CSS Custom Properties
No CSS custom properties are documented in the custom elements manifest.
CSS Parts
No CSS parts are documented in the custom elements manifest.
Read-only properties
These are computed getters exposed for rendering convenience — they do not appear in the generated API table above.
| Property | Type | Description |
|---|---|---|
canvasScaleX | number | Ratio of canvas backing-store pixels to CSS pixels along the x-axis. Equals devicePixelRatio when autoResizeCanvas is true. Use this as the x-scale factor in ctx.scale() to convert the canvas context to CSS pixel space. |
canvasScaleY | number | Ratio of canvas backing-store pixels to CSS pixels along the y-axis. |
Zoom and scale
rc-virtual-canvas is a pan-only viewport. It does not manage a content scale factor. Zoom (pinch-to-zoom, scroll-to-zoom) is the consumer's responsibility and should be applied by:
- Scaling the canvas context (
ctx.scale(zoom, zoom)) before drawing, and - Adjusting
contentWidthandcontentHeightto reflect the scaled content dimensions so the scrollable area matches.