tailwindcss-capsize

tailwindcss-capsize

A TailwindCSS plugin that generates text-box-trim utility classes using Capsize.

npm install --save-dev tailwindcss-capsize

text-box-trim?

Formerly known as leading-trim, a proposed CSS property to remove the extra space from text bounding boxes, which affects optical alignment. This article from Microsoft Design outlines the problem and how the proposed solution works.

Configuration

A JavaScript config file is required due to the values needed by the plugin.

@config "../tailwind.config.js";

Other Tailwind settings can be configured through CSS directives or included in the config file.

This plugin requires a fontMetrics key added to your Tailwind theme. It should be an object with keys matching those in your fontFamily definitions, and each key should have an object of the following shape:

{
	ascent: number
	descent: number
	lineGap: number
	unitsPerEm: number
	capHeight: number
}

These values can be determined by using the Capsize website, fontkit, FontDrop!, or some other means.

A full example

// tailwind.config.js
import pluginCapsize from 'tailwindcss-capsize'
export default {
	theme: {
		fontFamily: {
			sans: ['Inter', 'sans-serif'],
		},
		fontMetrics: {
			// Keys here must match those in fontFamily.
			sans: {
				capHeight: 2048,
				ascent: 2728,
				descent: -680,
				lineGap: 0,
				unitsPerEm: 2816,
			},
		},
		// ...
	},
	plugins: [pluginCapsize],
}

Usage

The new .capsize utility class should be applied to the direct parent element surrounding a text node. This class requires font-family, font-size, and line-height utilities to be applied at some point above it in the cascade in order for the required custom properties to be available.

<!-- Example using default TailwindCSS config -->

<p class="font-sans text-base leading-none capsize">Lorem ipsum dolor</p>

Options

rootSize

type: number (optional, default: 16)

The plugin assumes a root font-size of 16px when converting from rem values. To use a different value, pass it in (without units) to the plugin options.

pluginCapsize({ rootSize: 12 })

className

type: string (optional, default: 'capsize')

The default .capsize utility class can be replaced with a custom class name if preferred.

pluginCapsize({ className: 'leading-trim' })

Tips and tricks

Text truncation and line clamping

Sometimes an interface calls for truncating text to a single line or clamping text to a specified number of lines. Applying these methods to the same element that the default .capsize class is applied to will cause issues since the class assigns pseudo ::before and ::after elements to that element.

<!-- ❌ Does NOT work -->

<p class="font-sans text-base leading-none capsize truncate">
	Text to be truncated to a single line
</p>

To solve this, a child element to the element with the .capsize class should wrap the text. This element should receive the styling to truncate or line clamp.

<!-- ✅ Does work! -->

<p class="font-sans text-base leading-none capsize">
	<span class="truncate">Text to be truncated to a single line</span>
</p>

Related

🔡 tailwindcss-opentype — Utility classes for advanced typographic features.

Changelog

4.0.1

Patch Changes

• Handle number theme values (#261)

  Internal utilities assumed theme values would always be string typed, but in some cases they may be numbers.

• Handle anomalous values from Tailwind language server (#263)