sidebearing-trim
align text to visible ink, not the glyph box
Last verified:
What is sidebearing-trim?
sidebearing-trim is an npm package for optical text alignment on the web that aligns text by visible ink rather than by glyph box origin. It reads OpenType glyph metrics from font files and applies a negative line-start offset so columns align visually, fixing the pixel-sized alignment problem hidden in website headings where text appears misaligned due to sidebearing whitespace.
The tool works with both vanilla JavaScript and React. For vanilla JS, it exports a trimSidebearings function that takes an element and font source, returning a controller with recompute() and destroy() methods. For React, it provides a Sidebearing component that automatically re-runs when content or font changes and supports nested markup.
Key features include automatic resize observation, state inspection via getState(), the ability to re-run after dynamic content changes, CSS variable overlay support, and customizable glyph class names. It is designed for web developers, designers, and creative technologists who want pixel-perfect text alignment in headlines, columns, and any text where visual alignment matters more than box-based alignment.
The package is version 0.2.1 and is published on npm. It depends on opentype.js for parsing OpenType font metrics and injects spans around glyphs to measure and apply the sidebearing trim.
sidebearing-trim pricing
Pricing model: Freemium
This is a free and open-source npm package. Running 'npm install sidebearing-trim' installs it at no cost. There are no paid tiers, subscriptions, or licensing fees. The package is version 0.2.1 and can be used in both personal and commercial projects.
sidebearing-trim pros
- Aligns text by visible ink instead of glyph box origin
- Reads actual OpenType font metrics for accurate measurement
- Works with both vanilla JavaScript and React
- React component auto-re-runs when content or font changes
- Supports nested markup within trimmed elements
- Recomputes automatically on window resize by default
- Controller provides recompute() method for dynamic content
- Controller provides destroy() method to clean up DOM and listeners
- getState() method returns target count and line start statistics
- Can measure without trimming using trimEnabled option
- Supports URL, ArrayBuffer, or pre-parsed Font object as font source
- Customizable CSS variable name for overlay
- Customizable glyph class name for styling
- Lightweight bundle by supporting only WOFF format
- Developments console warning for font mismatch
sidebearing-trim cons
- Only .woff fonts are supported, no WOFF2
- WOFF2 support would add approximately 1.15 MB to bundle
- Requires mounted DOM nodes that are visible before trimming
- You must have the .woff file available at hand
- Font used in CSS must match fontSource exactly
- Font mismatch produces console warning in development
- Cannot work with system fonts without .woff file access
- Elements must be rendered before trimming runs
Frequently asked questions about sidebearing-trim
What problem does sidebearing-trim solve?
It fixes the visual alignment problem where text appears misaligned due to sidebearing whitespace in the first character. By extracting font metrics and detecting the starting characters of visual lines, it shifts each row by exactly the sidebearing value of its first glyph so columns align by visible ink.
Which font formats are supported?
Only .woff fonts are supported. WOFF2 support was not added because it would require approximately 1.15 MB of Brotli decompression code, significantly increasing the bundle size.
How do I use it in vanilla JavaScript?
Import trimSidebearings from sidebearing-trim, then call it with an element selector and font source path. It returns a controller with recompute() to re-measure after content changes and destroy() to clean up injected spans and event listeners.
How do I use it in React?
Import the Sidebearing component from sidebearing-trim/react. Use it as a wrapper element with the 'as' prop to specify the HTML tag, and provide fontSource as the path to your .woff file. The component re-runs automatically when content or font changes.
What happens if my font doesn't match?
The font used in CSS and the fontSource must point to the same file. If they mismatch, a console warning is produced in development mode to help you catch the issue.
Can I disable trimming but still measure?
Yes, set the trimEnabled option to false. This allows you to measure sidebearings without applying the trim, which can be useful for debugging or custom applications.
Does it handle window resize automatically?
Yes, by default observeResize is set to true, which means the tool re-runs on window resize to maintain correct alignment when layout changes.
What does the controller getState() method return?
It returns an object with targetCount (number of elements being trimmed), lineStartCount (number of line starts detected), and trimmedCount (number of lines that were actually trimmed).
Can I use it with dynamic content that changes after mount?
Yes, call the controller's recompute() method after layout or content changes to re-measure line starts and reapply the trim to the updated content.
What CSS variable does it set for overlays?
By default it sets the --lsb-em CSS variable when overlay is true. You can customize this using the overlayVariable prop to use a different CSS variable name.