/lineclamp

Limit an element's text to a given height or number of lines.

Primary LanguageJavaScript

LineClamp

Animation showing text resizing to stay one line long regardless of container width

Limit text to a given height or number of lines by reducing font size or trimming text. Works on inline and block elements with any combination of border, padding, line-height, min-height, and max-height.

Installation

npm install @tvanc/lineclamp

Examples

View examples on CodePen.

Usage

import LineClamp from "@tvanc/lineclamp"
const element = document.getElementById("#long-marketing-title")

// Create a clamp set to one line
const clamp = new LineClamp(element, { maxLines: 1 })

// Apply the clamp.
clamp.apply()

// Watch for layout changes, reclamp if necessary
clamp.watch()

// Stop watching
clamp.unwatch()

// Get text metrics (total height, number of lines, line heights)
// https://github.com/tvanc/lineclamp#getting-text-metrics
clamp.calculateTextMetrics()

Methods

Method Description
watch() Watch for changes.
unwatch() Stop watching for changes.
apply() Apply the clamp. Whether softClamp() or hardClamp() is used depends on the value of the useSoftClamp option.
softClamp() Reduce font size until text height or line count are within constraints. If font size is reduced to minFontSize and text still exceeds constraints, optionally resort to using hardClamp().
hardClamp() Trim text content to force it to fit within the maximum number of lines.
shouldClamp() Detect whether text exceeds the specified maxHeight or maxLines.
calculateTextMetrics() Get metrics regarding the element's text, like number of lines, text height, and line height.

Options

These options can be passed as the second argument to the constructor, or set directly on the object.

Option Type Default Description
maxLines Number 1 The maximum number of lines to allow. Defaults to 1. To set a maximum height instead, use maxHeight.
maxHeight Number undefined The maximum height (in pixels) of text in an element. This option is undefined by default. Once set, it takes precedence over maxLines. Note that this applies to the height of the text, not the element itself.
useSoftClamp Boolean false Whether to attempt soft clamping before resorting to hard clamping.
hardClampAsFallback Boolean true If true, resort to hard clamping if soft clamping reaches the minimum font size and still doesn't fit within the max height or number of lines
ellipsis Boolean 1 The character with which to represent clipped trailing text. This option takes effect when "hard" clamping is used.
minFontSize Boolean 1 The minimum font size before a soft clamp turns into a hard clamp.
maxFontSize Boolean computed font-size The maximum font size to use for the element when soft clamping. We start with this number and then decrement towards minFontSize.

Events

Add listeners to the clamped element, not the clamp itself.

Event Description
lineclamp.softclamp Emitted when the element is softly clamped.
lineclamp.hardclamp Emitted when the element is hard clamped.
lineclamp.clamp Emitted when any kind of clamping occurs. If .apply() results in both soft and hard clamping, only one lineclamp.clamp event is issued, after lineclamp.softclamp and lineclamp.hardclamp have fired.

Example

import LineClamp from "@tvanc/lineclamp"
const element = document.getElementById("#clampedElement")

const clamp = new LineClamp(element)
const listener = (event) => console.log(event.type)

element.addEventListener("lineclamp.softclamp", listener)
element.addEventListener("lineclamp.hardclamp", listener)
element.addEventListener("lineclamp.clamp", listener)

// softClamp() emits 'lineclamp.softclamp' and 'lineclamp.clamp', or nothing
// if clamping unnecessary
clamp.softClamp()

// hardClamp() emits 'lineclamp.hardclamp' and 'lineclamp.clamp', or nothing
// if clamping unnecessary
clamp.hardClamp()

// apply() can emit 'lineclamp.softclamp' and/or 'lineclamp.hardclamp' followed
// by 'lineclamp.clamp', or nothing if clamping is unnecessary
clamp.apply()

Getting Text Metrics

Unfortunately, there is no native API for counting the number of lines or determining line height. The computed CSS line-height can return normal, which isn't useful for calculations. The only (mostly) sure-fire solution is to compare the height of the element with no text to the height of the element with one line of text. That gets you the height of the first line.

Subsequent lines can have different heights than the first - though all subsequent lines will be the same height as each other (barring things that can distort line heights, like certain characters). So you have to add another line to know the height of the next lines.

This module does all that. The information it gleans is made available via the calculateTextMetrics() method:

import LineClamp from "@tvanc/lineclamp"
const element = document.getElementById("#long-marketing-title")
const clamp = new LineClamp(element)

// Get text metrics
const metrics = clamp.calculateTextMetrics()

calculateTextMetrics() returns an object with the following information.

Property Description
textHeight The vertical space in pixels required to display the element's current text.
naturalHeightWithOneLine The height of the element with only one line of text and without minimum or maximum heights.
firstLineHeight The height that the first line of text adds to the element, i.e., the difference between the height of the element while empty and the height of the element while it contains one line of text. This number may be zero for inline elements because the first line of text does not increase the height of inline elements.
additionalLineHeight The height that each line of text after the first adds to the element.
lineCount The number of lines of text the element contains.