CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-postcss-normalize-display-values

PostCSS plugin that normalizes CSS display property values by converting multiple-value display syntaxes into their equivalent single-value forms.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

PostCSS Normalize Display Values

PostCSS Normalize Display Values is a PostCSS plugin that normalizes CSS display property values by converting multiple-value display syntaxes into their equivalent single-value forms. This enables better browser compatibility and reduces CSS file size by transforming modern CSS display syntax into legacy-compatible values.

Package Information

  • Package Name: postcss-normalize-display-values
  • Package Type: npm
  • Language: JavaScript with TypeScript definitions
  • Installation: npm install postcss-normalize-display-values

Core Imports

const postcssNormalizeDisplayValues = require("postcss-normalize-display-values");

For ES modules (TypeScript/modern JavaScript projects use CommonJS export format):

import postcssNormalizeDisplayValues from "postcss-normalize-display-values";

Basic Usage

const postcss = require("postcss");
const postcssNormalizeDisplayValues = require("postcss-normalize-display-values");

// Use with PostCSS
const result = await postcss([
  postcssNormalizeDisplayValues()
]).process(css, { from: undefined });

console.log(result.css);

With a build tool like Webpack or Vite:

// postcss.config.js
module.exports = {
  plugins: [
    require("postcss-normalize-display-values")(),
    // other plugins...
  ],
};

Capabilities

Plugin Creator

Creates a PostCSS plugin instance that processes CSS display property values and converts multi-value syntaxes to single-value equivalents.

/**
 * Creates a PostCSS plugin that normalizes display property values
 * This is the default export of the postcss-normalize-display-values package
 * @returns PostCSS Plugin instance
 */
function pluginCreator(): Plugin;

Usage Example:

/* Input */
div {
  display: inline flow-root;
}

/* Output */
div {
  display: inline-block;
}

Display Value Transformations

The plugin automatically converts the following display value combinations:

Block-level Display Values

/* Multi-value → Single-value */
display: block flow;           /* → block */
display: block flow-root;      /* → flow-root */
display: list-item block flow; /* → list-item */
display: block flex;           /* → flex */
display: block grid;           /* → grid */
display: block table;          /* → table */

Inline-level Display Values

/* Multi-value → Single-value */
display: inline flow;          /* → inline */
display: inline flow-root;     /* → inline-block */
display: inline flex;          /* → inline-flex */
display: inline grid;          /* → inline-grid */
display: inline table;         /* → inline-table */
display: inline ruby;          /* → ruby */
display: inline flow list-item; /* → inline list-item */

Special Display Values

/* Multi-value → Single-value */
display: run-in flow;          /* → run-in */
display: table-cell flow;      /* → table-cell */
display: table-caption flow;   /* → table-caption */
display: ruby-base flow;       /* → ruby-base */
display: ruby-text flow;       /* → ruby-text */

Plugin Behavior

The plugin:

  • Processes only display properties (case-insensitive matching)
  • Uses caching to avoid redundant transformations of duplicate values
  • Preserves original values when no transformation mapping exists
  • Handles CSS variables and complex expressions by passing them through unchanged
  • Ignores empty or malformed values gracefully
  • Executes during PostCSS OnceExit phase for optimal performance

Types

/**
 * PostCSS Plugin type from the postcss package
 */
interface Plugin {
  postcssPlugin: string;
  prepare(): {
    OnceExit(css: Root): void;
  };
}

/**
 * Plugin creator function signature
 */
type PluginCreator = () => Plugin;

/**
 * Plugin marker property indicating PostCSS compatibility
 */
interface PluginCreator {
  postcss: true;
}

Error Handling

The plugin is designed to be fault-tolerant:

  • Invalid display values: Passed through unchanged
  • CSS variables: Preserved as-is (e.g., display: var(--my-display))
  • Complex expressions: Left untouched (e.g., display: var(--foo) var(--bar))
  • Non-display properties: Ignored completely
  • Empty values: Skipped without error

Browser Compatibility

This plugin helps maintain compatibility by converting newer CSS Display Level 3 multi-value syntax to widely-supported single-value equivalents. The transformations are based on the CSS Display Level 3 specification.

Modern browsers support both syntaxes, but older browsers and some CSS minifiers work better with single-value display properties.

Install with Tessl CLI

npx tessl i tessl/npm-postcss-normalize-display-values
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/postcss-normalize-display-values@7.0.x
Publish Source
CLI
Badge
tessl/npm-postcss-normalize-display-values badge