1. Installation & Setup
# Install via NPM
npm install @modracx/ruler-js
# Or include via CDN script tag
<script src="https://cdn.jsdelivr.net/npm/@modracx/ruler-js/dist/ruler.min.js"></script>
2. Quick Start Example
import { Ruler } from '@modracx/ruler-js';
// Initialize ruler on the active document body
const ruler = new Ruler({
theme: 'dark',
unit: 'px',
snapTolerance: 5,
showGuides: true,
onMeasure: (dimensions) => {
console.log(`Width: ${dimensions.width}px, Height: ${dimensions.height}px`);
}
});
// Toggle ruler visibility on keyboard shortcut (e.g. Ctrl + Shift + R)
window.addEventListener('keydown', (e) => {
if (e.ctrlKey && e.shiftKey && e.key === 'R') {
ruler.toggle();
}
});
3. Options & Configuration Reference
| Option Property |
Type |
Default |
Description |
theme |
'dark' | 'light' | 'gold' |
'dark' |
Visual theme preset for rulers and guide overlays |
unit |
'px' | 'rem' | 'em' | 'percent' |
'px' |
Measurement unit displayed in the dimension readout tooltip |
snapTolerance |
number |
5 |
Pixel threshold distance to snap guides to nearby DOM element edges |
showGuides |
boolean |
true |
Enable dragging horizontal and vertical guideline rules from headers |
4. Keyboard Shortcuts Matrix
| Key Binding |
Action |
| Shift + Drag |
Constrain box selection to a perfect 1:1 square aspect ratio |
| Alt (Option) |
Display relative distance between selected box and closest parent container |
| Arrow Keys |
Nudge active guide or measurement box by 1 pixel |
| Shift + Arrow Keys |
Nudge active guide by 10 pixels |
| Escape |
Clear current selection and remove active measurement guide |
Related Tools & Documentation