stylelint-plugin-logical-css

A Stylelint plugin to enforce the use of logical CSS properties, values and units for adaptive, i18n-first styles.

V1 documentation can be found here

Table of Contents

Getting Started | Quickstart | Plugin Configs | Plugin Rules | Troubleshooting | Upgrading from 1.x → 2.x

Getting Started

The plugin requires Stylelint v14.0.0 or greater.

To get started using the plugin, it must first be installed.

npm i stylelint-plugin-logical-css --save-dev

yarn add stylelint-plugin-logical-css --dev

With the plugin installed, it must be added to the plugins array of your Stylelint config.

{
  "plugins": ["stylelint-plugin-logical-css"],
}

After adding the plugin to the configuration file, you now have access to the various rules and options it provides.

Quickstart

After installation, add this to your .stylelintrc.json:

{
  "plugins": ["stylelint-plugin-logical-css"],
  "extends": ["stylelint-plugin-logical-css/configs/recommended"]
}

Logical CSS Configs

For quick setup, the plugin provides preset configurations that enable commonly used rules.

Recommended

The recommended preset enables core logical CSS rules with sensible defaults, suitable for most projects.

Usage:

{
  "extends": ["stylelint-plugin-logical-css/configs/recommended"]
}

Equivalent to:

{
  "plugins": ["stylelint-plugin-logical-css"],
  "rules": {
    "logical-css/require-logical-keywords": [
      true,
      { "ignore": ["caption-side", "offset-anchor", "offset-position"], "severity": "error" },
    ],
    "logical-css/require-logical-properties": [true, { "severity": "error" }],
    "logical-css/require-logical-units": [true, { "severity": "error" }],
  },
}

Logical CSS Rules

The plugin provides multiple rules that can be toggled on and off as needed.

1. Require Logical Keywords
2. Require Logical Properties
3. Require Logical Units

Require Logical Keywords

Read about current browser support for logical CSS properties.

Physical CSS directional keywords like left, right, top, bottom, horizontal, and vertical reference absolute directions that don't adapt to writing modes or text direction. Logical keywords like start, end, inline-start, block-end, inline, and block automatically adjust based on the document's writing mode, supporting internationalization and adaptive layouts.

Enable this rule to: Enforce the use of logical CSS directional keywords (start, end, inline-start, block-end, inline, block, etc.) over their physical equivalents (left, right, top, bottom, horizontal, vertical) in property values, ensuring your styles adapt properly to different writing modes and text directions.

{
  "rules": {
    "logical-css/require-logical-keywords": true,
  }
}

Require Logical Keywords Options

type Severity = 'error' | 'warning';

interface SecondaryOptions {
  fix?: boolean;
  ignore?: PhysicalKeywordProperty[],
  severity?: Severity
}

{
  "rules": {
    "logical-css/require-logical-keywords": [true, {
      "fix": true,
      "ignore": ["caption-side", "offset-anchor"],
      "severity": "error",
    }]
  }
}

Require Logical Keywords Map

The following table shows how physical CSS directional keywords are mapped to their logical equivalents. When this rule detects a physical keyword, it will suggest (or automatically fix, if enabled) the corresponding logical keyword.

Require Logical Keywords Examples

.text {
  text-align: start;
  text-align-last: end;
}

.layout {
  float: inline-start;
  clear: inline-end;
}

.box {
  resize: inline;
}

.table {
  caption-side: block-start;
}

.legacy {
  box-orient: inline-axis;
}

.positioned {
  offset-anchor: block-end inline-start;
  offset-position: block-start inline-end;
}

.text {
  text-align: left;
  text-align-last: right;
}

.layout {
  float: left;
  clear: right;
}

.box {
  resize: horizontal;
}

.table {
  caption-side: top;
}

.legacy {
  box-orient: vertical;
}

.positioned {
  offset-anchor: bottom left;
  offset-position: top right;
}

Require Logical Properties

Read about current browser support for logical CSS properties.

Physical CSS properties like width, height, left, and margin-top reference absolute dimensions and directions that don't adapt to writing modes or text direction. Logical properties like inline-size, block-size, inset-inline-start, and margin-block-start automatically adjust based on the document's writing mode, supporting internationalization and adaptive layouts.

Enable this rule to: Enforce the use of logical CSS properties (inline-size, block-size, margin-inline, padding-block, etc.) over their physical equivalents (width, height, margin-left, padding-top, etc.), ensuring your styles adapt properly to different writing modes and text directions.

{
  "rules": {
    "logical-css/require-logical-properties": true,
  }
}

Require Logical Properties Options

Configuration: By default, this rule validates all CSS declarations for any use of physical properties (width, height, top, left, margin-left, padding-top, etc.). Use the rule options to exclude specific physical properties from validation, automate physical-to-logical property fixing, or adjust the severity level as needed.

type Severity = 'error' | 'warning';

interface SecondaryOptions {
  fix?: boolean;
  ignore?: PhysicalProperty[],
  severity?: Severity
}

{
  "rules": {
    "logical-css/require-logical-properties": [true, {
      "fix": true,
      "ignore": ["height", "scroll-margin-bottom", "width"],
      "severity": "error",
    }]
  }
}

Require Logical Properties Map

The following table shows how physical CSS properties are mapped to their logical equivalents. When this rule detects a physical property, it will suggest (or automatically fix, if enabled) the corresponding logical property.

Require Logical Properties Examples

.element {
  inline-size: 100%;
  block-size: 50vh;
}

.box {
  margin-block-start: 1rem;
  margin-inline: 2rem;
  padding-block: 10px;
  padding-inline-end: 20px;
}

.positioned {
  inset-inline-start: 0;
  inset-block-end: 10px;
}

.borders {
  border-inline-start: 1px solid black;
  border-block-end-color: red;
  border-start-start-radius: 8px;
}

.element {
  width: 100%;
  height: 50vh;
}

.box {
  margin-top: 1rem;
  margin-left: 2rem;
  margin-right: 2rem;
  padding-top: 10px;
  padding-bottom: 10px;
  padding-right: 20px;
}

.positioned {
  left: 0;
  bottom: 10px;
}

.borders {
  border-left: 1px solid black;
  border-bottom-color: red;
  border-top-left-radius: 8px;
}

Require Logical Units

Read about current browser support for logical CSS units.

Physical CSS units like vh (viewport height) and vw (viewport width) reference absolute dimensions that don't adapt to writing modes or text direction. Logical units like vb (viewport block) and vi (viewport inline) automatically adjust based on the document's writing mode, supporting internationalization and adaptive layouts.

Enable this rule to: Enforce the use of logical CSS units (vb, vi, cqb, cqi, etc.) over their physical equivalents (vh, vw, cqh, cqw, etc.), ensuring your styles adapt properly to different writing modes and text directions.

{
  "rules": {
    "logical-css/require-logical-units": true,
  }
}

Require Logical Units Options

Configuration: By default, this rule validates all CSS properties for any use of physical units (vh, vw, dvh, dvw, lvh, lvw, svh, svw, cqh, cqw). Use the rule options to exclude specific physical units from validation, automate physical-to-logical unit fixing, or adjust the severity level as needed.

type Severity = 'error' | 'warning';

interface SecondaryOptions {
  fix?: boolean;
  ignore?: PhysicalUnit[],
  severity?: Severity
}

{
  "rules": {
    "logical-css/require-logical-units": [true, {
      "fix": true,
      "ignore": ["vh", "dvw"],
      "severity": "error",
    }]
  }
}

Require Logical Units Map

The following table shows how physical CSS units are mapped to their logical equivalents. When this rule detects a physical unit, it will suggest (or automatically fix, if enabled) the corresponding logical unit.

Require Logical Units Examples

.element {
  block-size: 100vb;
  inline-size: 80vi;
}

.card {
  max-block-size: 50cqb;
  max-inline-size: 100cqi;
}

.hero {
  min-block-size: 100dvb;
  inline-size: min(80vi, 100%);
}

.responsive {
  inline-size: clamp(20vi, 50%, 80vi);
}

.element {
  height: 100vh;
  width: 80vw;
}

.card {
  max-height: 50cqh;
  max-width: 100cqw;
}

.hero {
  min-height: 100dvh;
  width: min(80vw, 100%);
}

.responsive {
  width: clamp(20vw, 50%, 80vw);
}

.partial {
  width: 50.5vw;
}

Troubleshooting

Ignoring Specific Patterns

As an escape hatch, use Stylelint's built-in disable comments to bypass specific rules:

div {
  /* stylelint-disable-next-line logical-css/require-logical-properties */
  width: 100%;
}

Upgrading from 1.x → 2.x

To upgrade from 1.x (v1 documentation) to 2.x, update your Stylelint configuration as follows:

1. Remove legacy rules

The rules have changed from v1.x to v2.x. Remove any legacy rules (plugin/use-logical-*) from your Stylelint configuration.

2a. Use the recommended configuration

Add the recommended preset to your extends array:

{
  "extends": ["stylelint-plugin-logical-css/configs/recommended"]
}

… or …

2b. Migrate custom rule configurations

In v2, several rules were renamed and separated for improved granularity. If you previously configured these rules manually, update them as follows:

If you relied on custom rule configuration in v1, you must explicitly configure the corresponding v2 rules.