Trackball.js is a small JavaScript library on top of Quaternion.js that enables natural, free 3D rotation of DOM elements via CSS transforms. The library does not style your DOM – it just handles user input and gives you a quaternion that you apply to your object.
If you are interested in the math behind this library or want to see a demo, take a look at the derivation of the trackball.
Example
The usage of Trackball.js is pretty straightforward. Create a scene that should handle the input and put a object with 3D transforms in it:
setActiveArea(area) – change the active area at runtime.
setEnabled(boolean) – enable/disable interaction.
dispose() – remove listeners and stop inertia.
Notes
Trackball.js only computes the quaternion. Apply it to your object any way you like, e.g. q.toCSSTransform().
To restrict to a sub-rect of the scene, provide activeArea (element, selector, rect, or function).
Coding Style
As every library I publish, Trackball.js is also built to be as small as possible after compressing it with Google Closure Compiler in advanced mode. Thus the coding style orientates a little on maxing-out the compression rate. Please make sure you keep this style if you plan to extend the library.
Building the library
After cloning the Git repository run:
npm installnpm run build
Run a test
Testing the source against the shipped test suite is as easy as
npm run test
Copyright and Licensing
Copyright (c) 2025, Robert Eisele
Licensed under the MIT license.