Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/marcbouchenoire/typometer
🖊️ Measure text asynchronously.
https://github.com/marcbouchenoire/typometer
canvas measure metrics offscreen text
Last synced: 13 days ago
JSON representation
🖊️ Measure text asynchronously.
- Host: GitHub
- URL: https://github.com/marcbouchenoire/typometer
- Owner: marcbouchenoire
- License: mit
- Created: 2021-04-30T16:06:24.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-06-17T20:59:45.000Z (5 months ago)
- Last Synced: 2024-10-17T01:30:06.696Z (28 days ago)
- Topics: canvas, measure, metrics, offscreen, text
- Language: TypeScript
- Homepage: https://marcbouchenoire.com/projects/typometer
- Size: 2.11 MB
- Stars: 24
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 
🖊️ Measure text asynchronously.
[](https://github.com/marcbouchenoire/typometer/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/typometer)
[](https://bundlephobia.com/package/typometer)
[](https://codecov.io/gh/marcbouchenoire/typometer)
[](https://github.com/marcbouchenoire/typometer/blob/main/LICENSE)
- 🗜️ **Small**: Just around **1 kB** on modern platforms
- ⚡️ **Multi-threaded**: Run from a [Worker](https://developer.mozilla.org/en-US/docs/Web/API/Worker/Worker) when [OffscreenCanvas](https://developer.mozilla.org/en-US/docs/Web/API/OffscreenCanvas) is supported
- 🧪 **Reliable**: Fully tested with [100% code coverage](https://codecov.io/gh/marcbouchenoire/typometer)
- 📦 **Typed**: Written in [TypeScript](https://www.typescriptlang.org/) and includes definitions out-of-the-box
- 💨 **Zero dependencies**
## Introduction
Measuring text performantly in the browser isn't as straightforward as one would think—the recommended way is to leverage the [Canvas API](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API) (and its [`measureText`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/measureText) method) instead of relying on the DOM directly. Typometer embraces this way into a single function and attempts to smooth out the differences between the DOM and the Canvas API.
When supported, Typometer will leverage an [OffscreenCanvas](https://developer.mozilla.org/en-US/docs/Web/API/OffscreenCanvas) from a [Worker](https://developer.mozilla.org/en-US/docs/Web/API/Worker/Worker) to measure in a background thread.
#### Name
Typometer is named after [a physical ruler](https://en.wikipedia.org/wiki/Typometer) used to measure in typographic points.
## Installation
```bash
npm install typometer
```
## Usage
Import `typometer`.
```typescript
import { typometer } from "typometer"
```
Invoke it asynchronously with a string and access serialized [`TextMetrics`](https://developer.mozilla.org/en-US/docs/Web/API/TextMetrics) in return.
```typescript
const metrics = await typometer("With impressions chosen from another time.")
// metrics: {
// actualBoundingBoxAscent: 8,
// actualBoundingBoxDescent: 3,
// actualBoundingBoxLeft: 0,
// actualBoundingBoxRight: 195.0732421875,
// alphabeticBaseline: 0,
// emHeightAscent: 10,
// emHeightDescent: 2,
// fontBoundingBoxAscent: 10,
// fontBoundingBoxDescent: 2,
// hangingBaseline: 10,
// ideographicBaseline: -2,
// width: 195.0732421875
// }
```
Given an array of strings instead, `typometer` will return an array of serialized [`TextMetrics`](https://developer.mozilla.org/en-US/docs/Web/API/TextMetrics).
```typescript
const metrics = await typometer([
"With impressions chosen from another time.",
"Underneath a sky that's ever falling down."
])
// metrics: [TextMetrics, TextMetrics]
```
## Options
### Font
A secondary argument can be set to specify a font appearance—from [properties](#properties), a [`font`](#string) string, or a [`CSSStyleDeclaration`](#CSSStyleDeclaration).
#### Properties
Specify individual font properties as an object with [`fontFamily`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-family), [`fontSize`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-size), [`fontStretch`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-stretch), [`fontStyle`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style), [`fontVariant`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant), [`fontWeight`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight), and [`lineHeight`](https://developer.mozilla.org/en-US/docs/Web/CSS/line-height).
```typescript
const metrics = await typometer("", {
fontFamily: "cursive",
fontSize: 16,
fontStyle: "italic",
fontWeight: 500,
fontVariant: "small-caps",
lineHeight: 2
})
```
##### `string`
Specify all font properties as a [`font`](https://developer.mozilla.org/en-US/docs/Web/CSS/font) shorthand string.
```typescript
const metrics = await typometer("", "italic small-caps 500 16px/2 cursive")
```
##### `CSSStyleDeclaration`
Specify a [`CSSStyleDeclaration`](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleDeclaration) from which to extract font properties.
```typescript
const paragraph = document.querySelector("p")
const metrics = await typometer("", window.getComputedStyle(paragraph))
```