{"id":12116,"library":"tailwindcss-capsize","title":"TailwindCSS Capsize Plugin","description":"tailwindcss-capsize is a TailwindCSS plugin that addresses the long-standing problem of inconsistent text alignment caused by the \"extra space\" in font bounding boxes, often referred to as leading-trim or text-box-trim. It leverages the Capsize library to generate utility classes that optically align text by adjusting content box edges to match the capital height and baseline of the font. The current stable version is 4.0.1, with patch releases occurring regularly and major versions typically aligning with significant updates to TailwindCSS itself, such as the recent v4 release. Its key differentiator is providing a robust, configuration-driven solution within the Tailwind ecosystem for precise typographic control, relying on `fontMetrics` specific to the fonts used in a project. This plugin is crucial for designers and developers aiming for pixel-perfect typography and consistent vertical rhythm in their web applications, overcoming browser inconsistencies in text rendering. It requires a `tailwindcss` peer dependency and ships with TypeScript types.","status":"active","version":"4.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/stormwarning/tailwindcss-capsize","tags":["javascript","tailwindcss","tailwindcss-plugin","capsize","leading-trim","text-box","text-box-trim","typography","whitespace","typescript"],"install":[{"cmd":"npm install tailwindcss-capsize","lang":"bash","label":"npm"},{"cmd":"yarn add tailwindcss-capsize","lang":"bash","label":"yarn"},{"cmd":"pnpm add tailwindcss-capsize","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for the plugin to function within a TailwindCSS project.","package":"tailwindcss","optional":false}],"imports":[{"note":"Since Node.js >=20 is required, ESM syntax (`import`) is the standard and recommended way to load the plugin in `tailwind.config.js` or `tailwind.config.ts`. CommonJS `require()` might work for older setups but is not officially supported by the plugin's `engines` field.","wrong":"const pluginCapsize = require('tailwindcss-capsize')","symbol":"default","correct":"import pluginCapsize from 'tailwindcss-capsize'"},{"note":"Useful for providing type hints to the plugin's configuration object in TypeScript-based `tailwind.config.ts` files, allowing IDEs to validate options like `rootSize` or `className`.","symbol":"CapsizeOptions","correct":"import type { CapsizeOptions } from 'tailwindcss-capsize'"}],"quickstart":{"code":"// tailwind.config.ts\nimport type { Config } from 'tailwindcss';\nimport pluginCapsize from 'tailwindcss-capsize';\nimport type { CapsizeOptions } from 'tailwindcss-capsize';\n\nconst config: Config = {\n  content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],\n  theme: {\n    extend: {\n      fontFamily: {\n        sans: ['Inter', 'sans-serif'],\n      },\n      fontMetrics: {\n        // These values should be obtained from your font files using tools like Capsize website, fontkit, or FontDrop!\n        // The keys here MUST match those defined in your `fontFamily` object.\n        sans: {\n          capHeight: 2048,\n          ascent: 2728,\n          descent: -680,\n          lineGap: 0,\n          unitsPerEm: 2816,\n        },\n        // Add metrics for other font families you use, e.g., serif: {...}\n      },\n    },\n  },\n  plugins: [\n    pluginCapsize({\n      // Optional: Adjust rootSize if your HTML root font-size is not 16px\n      rootSize: 16,\n      // Optional: Customize the utility class name from 'capsize' to something else\n      // className: 'leading-trim-active'\n    } as CapsizeOptions), // Casting helps ensure type safety for plugin options\n  ],\n};\n\nexport default config;\n\n// index.html or a React/Vue component usage\n/*\n<style>\n  @tailwind base;\n  @tailwind components;\n  @tailwind utilities;\n</style>\n<div class=\"p-8\">\n  <p class=\"font-sans text-xl leading-relaxed capsize\">\n    <span>This text will have precise optical alignment due to Capsize.</span>\n  </p>\n  <p class=\"font-sans text-base leading-normal capsize\">\n    <span>Another example of precisely aligned text.</span>\n  </p>\n  <p class=\"font-serif text-lg leading-tight capsize\">\n    <span>Even serif fonts can benefit from leading-trim.</span>\n  </p>\n</div>\n*/","lang":"typescript","description":"Demonstrates how to configure `tailwindcss-capsize` in a `tailwind.config.ts` file with required font metrics and its basic usage in HTML for optically aligned text."},"warnings":[{"fix":"Review generated CSS for redundant `fontSize` and `lineHeight` declarations. While usage remains similar, be aware of increased CSS payload. Consider adjusting your Tailwind configuration or CSS post-processing if this is an issue.","message":"Upgraded for Tailwind CSS v4, which involved significant changes to plugin configuration and capabilities. The plugin no longer disables `corePlugins` like `fontSize` directly, leading to duplicate CSS declarations in the output if custom properties are included in the same utilities.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"If previous functionality (prior to v3) is required, explicitly configure the plugin to use `classic` mode: `pluginCapsize({ mode: 'classic' })`. Otherwise, ensure your styles are tested with the new modern output.","message":"The default `modern` output mode was introduced, which replaces Tailwind's core `fontFamily`, `fontSize`, and `lineHeight` plugins with custom property-enabled versions. This changes the underlying CSS output for these utilities.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Thoroughly review all text-heavy components after upgrading to `v2.0.0` to ensure the optical alignment still meets design specifications. The underlying CSS properties and values generated by Capsize will be different.","message":"The plugin adopted the new `@capsize/core` library, which simplified the leading trim technique. This change *will* alter the final output CSS, requiring re-evaluation of design systems for visual consistency.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Wrap the text content within a child element. Apply the `.capsize` class to the parent, and the truncation/line-clamping classes to the child element. Example: `<p class='capsize'><span class='truncate'>...</span></p>`.","message":"Applying text truncation or line clamping utilities (e.g., `truncate`, `line-clamp-N`) directly to an element with the `.capsize` class can cause rendering issues because `.capsize` uses `::before` and `::after` pseudo-elements to perform the leading trim.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Ensure `fontMetrics` are correctly defined in `tailwind.config.js` for all font families you intend to use with `capsize`. Use tools like the Capsize website or FontDrop! to obtain these precise metrics for your fonts.","message":"The plugin requires a `fontMetrics` key in your Tailwind theme configuration, with specific `ascent`, `descent`, `lineGap`, `unitsPerEm`, and `capHeight` values for each `fontFamily` entry. Without these, the plugin cannot calculate correct leading trim values.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Verify the `.capsize` class is on the immediate parent of the text, and that necessary font styles (like `font-sans`, `text-base`, `leading-none`) are defined higher up or on the same element. Example: `<p class='font-sans text-base leading-none capsize'>Lorem ipsum dolor</p>`.","message":"The `.capsize` utility class must be applied to the *direct parent* of the text node. Additionally, `font-family`, `font-size`, and `line-height` utilities must be applied somewhere in the cascade above the `.capsize` element for the required custom properties to be available.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Add the `fontMetrics` object to your Tailwind theme, ensuring it contains the correct `ascent`, `descent`, `lineGap`, `unitsPerEm`, and `capHeight` values for each font family used. The keys in `fontMetrics` must match those in `fontFamily`.","cause":"The `fontMetrics` object is not configured in `tailwind.config.js` or is missing metrics for a font family actively used with the plugin.","error":"Theme value for `fontMetrics` is missing or invalid for font: [font-name]"},{"fix":"Ensure `font-family`, `font-size`, and `line-height` Tailwind utilities are applied to the element containing the `.capsize` class, or its ancestors, to correctly define the CSS custom properties (`--font-size-px`, `--line-height-unitless`, etc.) required by the plugin.","cause":"The `.capsize` class is applied, but the required `font-size` or `line-height` utilities (which populate custom CSS properties in `modern` mode) are missing on the element or its ancestors.","error":"Property `--font-size` is undefined"},{"fix":"Update to `tailwindcss-capsize@4.0.1` or newer. This issue was addressed in patch release `v4.0.1` by improving internal handling of theme value types.","cause":"Internal utilities assumed theme values would always be `string` typed, but in some cases, such as `fontSize` values defined as numbers in the theme, they may be `number`s. This issue specifically affects plugin logic.","error":"TypeError: Cannot read properties of undefined (reading 'length') for theme values"},{"fix":"Wrap the text content in a child `<span>` or similar element. Apply the `.capsize` class to the parent element, and apply the truncation/line-clamping utilities to the child element. Example: `<p class='capsize'><span class='truncate'>...</span></p>`.","cause":"Text truncation or line clamping utilities (`truncate`, `line-clamp-N`) are applied directly to the element that also has the `.capsize` class.","error":"Text truncation/clamping visually incorrect or broken when using .capsize"}],"ecosystem":"npm"}