Add Customizable Measurement Rulers to Web Pages with ruler-js

ruler-js is a tiny JavaScript plugin for generating horizontal and vertical rulers with support for multiple units and interactive crosshairs. Works as both a standalone JavaScript library and a jQuery plugin.

The plugin handles DPI calculations automatically and adapts to window resizing without additional configuration. It's ideal for developers building design tools, prototyping interfaces, or debugging complex layouts where pixel-perfect measurements matter.

Features:

• Multiple Unit Support: Measures in inches, centimeters, millimeters, and pixels with configurable decimal precision.
• Interactive Crosshair System: Displays real-time crosshair lines that track mouse movement with customizable colors and line styles.
• Live Position Feedback: Shows current mouse coordinates in a floating box that updates dynamically as you move across the viewport.
• Automatic DPI Detection: Calculates pixels-per-inch based on browser rendering to approximate real-world measurements accurately.
• Customizable Appearance: Configure ruler dimensions, tick colors, crosshair styles, and mouse position box styling to match your application's design.
• Responsive Design: Automatically recalculates and redraws tick marks when the window resizes.

Use Cases:

• Design implementation verification: Compare developed layouts directly against designer mockups by measuring spacing, dimensions, and alignment in actual browsers .
• Responsive breakpoint testing: Check how element proportions and spacing scale across different screen sizes using real-world units rather than just pixels .
• CSS framework customization: Precisely measure grid systems, component spacing, and container widths when customizing frameworks like Bootstrap or Tailwind CSS .
• Educational demonstrations: Visually explain CSS positioning, margin, padding, and alignment concepts during teaching or knowledge sharing sessions .

How To Use It:

1. Download the source file and load the ruler-js library in the document.

<!-- Vanilla JS -->
<script src="/path/to/ruler.js"></script>

<!-- As a jQuery Plugin -->
<script src="/path/to/cdn/jquery.slim.min.js"></script>
<script src="/path/to/ruler-jquery.js"></script>

2. Create a ruler by calling the static Ruler.create() method, passing the container element and an options object.

// Vanilla JS
const container = document.getElementById("rulerContainer");
Ruler.create(container, {
  // options here
});

// As a jQuery Plugin
$("#rulerContainer").Ruler("create", {
  // options here
});

3. Configure the ruler by passing the following configuration options.

• vRuleSize: Sets the width of the vertical ruler in pixels.
• hRuleSize: Sets the height of the horizontal ruler in pixels.
• showCrosshair: A boolean (true or false) that toggles the crosshair lines following the mouse.
• showMousePos: A boolean (true or false) that toggles the floating box showing the mouse's x/y coordinates.
• tickColor: A string defining the color of the ruler's tick marks (e.g., "#323232").
• crosshairColor: A string defining the color of the crosshair lines.
• crosshairStyle: A string defining the line style of the crosshair (e.g., "solid", "dotted", "dashed").
• mouseBoxBg: A string defining the background color of the mouse position box.
• mouseBoxColor: A string defining the text color of the mouse position box.
• unit: A string that sets the measurement unit. Accepts "in", "cm", "mm", or "px".
• unitPrecision: A number that sets the decimal precision for the displayed measurements.

{
  vRuleSize: 18,
  hRuleSize: 18,
  showCrosshair: true,
  showMousePos: true,
  tickColor: "#323232",
  crosshairColor: "#000",
  crosshairStyle: "dotted",
  mouseBoxBg: "#323232",
  mouseBoxColor: "#fff",
  unit: "in",
  unitPrecision: 1,
}

4. API methods.

Vanilla JavaScript

• Ruler.create(container, options): Initializes and renders the ruler inside the specified container DOM element. The options parameter is an object with any of the configuration options listed above.
• Ruler.clear(container): Removes the ruler, its associated DOM elements, and event listeners from the specified container.

jQuery

• .Ruler("create", options): The jQuery equivalent of the create method. You call it on a jQuery object (e.g., $("#rulerContainer").Ruler("create", {...})).
• .Ruler("clear"): The jQuery equivalent of the clear method. It removes the ruler from the element it's called on.

FAQs

Q: Can I use different units for horizontal and vertical rulers?
A: No, the library applies the same unit setting to both rulers. If you need different units per axis, you would need to initialize two separate ruler instances on different containers and position them appropriately, though this creates complexity around crosshair synchronization.

Q: The measurements don't match my design software exactly. Why?
A: Browsers calculate CSS inches based on a standard 96 DPI reference rather than your display's actual pixel density. Your monitor might have 120 PPI or 220 PPI physically, but CSS treats it as 96 DPI unless the browser applies scaling. For precise measurements that match design tools, use pixel units instead of physical units.

Q: How do I prevent the ruler from interfering with clicks on my interface?
A: The ruler elements use pointer-events: none in their CSS, which allows mouse interactions to pass through to underlying content. Clicks, hovers, and other pointer events will work normally on your interface elements beneath the ruler overlay.

Q: Can I customize the tick mark intervals?
A: The library uses fixed intervals (0.1 units for inches/centimeters/millimeters, 10 pixels for pixel mode) that aren't exposed as configuration options. Modifying intervals requires editing the source code in the renderTicks function where the step value is defined. You can adjust the major, medium, and small tick logic in the getTickType function.

Q: The ruler disappears when I update my page content dynamically. How do I fix this?
A: Dynamic DOM updates that replace or remove the container element will destroy the ruler. After updating content, check if the container still exists and reinitialize the ruler if needed. Store your ruler configuration in a variable and call Ruler.create() again after DOM updates complete. The library's cleanup function prevents duplicate rulers if you call create multiple times on the same element.

---

This awesome jQuery plugin is developed by Modracx. For more Advanced Usages, please check the demo page or visit the official website.