or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-emotion--unitless

An object of CSS properties that don't accept values with units

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@emotion/unitless@0.10.x

To install, run

npx @tessl/cli install tessl/npm-emotion--unitless@0.10.0

index.mddocs/

@emotion/unitless

@emotion/unitless is a utility library that provides a comprehensive object of CSS properties that don't accept unit values. This package is essential for CSS-in-JS libraries to automatically determine when to omit units from numeric style values, enabling proper styling for properties like flex, opacity, and zIndex that should remain unitless.

Package Information

  • Package Name: @emotion/unitless
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @emotion/unitless

Core Imports

import unitless from "@emotion/unitless";

For CommonJS:

const unitless = require("@emotion/unitless");

Basic Usage

import unitless from "@emotion/unitless";

// Check if a CSS property should be unitless
if (unitless.flex) {
  // flex property doesn't need units: flex: 1 (not flex: 1px)
}

if (!unitless.width) {
  // width property needs units: width: 100px (not width: 100)
}

// Common usage in CSS-in-JS libraries
function addUnitsIfNeeded(property: string, value: number): string {
  if (unitless[property]) {
    return value.toString();
  }
  return value + 'px';
}

// Examples:
addUnitsIfNeeded('flex', 1);        // Returns: "1"
addUnitsIfNeeded('opacity', 0.5);   // Returns: "0.5"
addUnitsIfNeeded('width', 100);     // Returns: "100px"
addUnitsIfNeeded('height', 50);     // Returns: "50px"

Capabilities

Unitless Property Detection

The main functionality is a single object that maps CSS property names to the value 1 for properties that should not have units when given numeric values.

/**
 * Object containing CSS properties that don't accept unit values
 * Each property maps to 1 if it's unitless, undefined otherwise
 */
declare const unitless: Record<string, 1>;
export default unitless;

Properties included (47 total):

Animation Properties:

  • animationIterationCount: 1

Aspect Ratio:

  • aspectRatio: 1

Border Image Properties:

  • borderImageOutset: 1
  • borderImageSlice: 1
  • borderImageWidth: 1

Legacy Box Model (deprecated but supported):

  • boxFlex: 1
  • boxFlexGroup: 1
  • boxOrdinalGroup: 1

Column Properties:

  • columnCount: 1
  • columns: 1

Flexbox Properties:

  • flex: 1
  • flexGrow: 1
  • flexPositive: 1
  • flexShrink: 1
  • flexNegative: 1
  • flexOrder: 1

CSS Grid Properties:

  • gridRow: 1
  • gridRowEnd: 1
  • gridRowSpan: 1
  • gridRowStart: 1
  • gridColumn: 1
  • gridColumnEnd: 1
  • gridColumnSpan: 1
  • gridColumnStart: 1

Microsoft Grid Properties (legacy):

  • msGridRow: 1
  • msGridRowSpan: 1
  • msGridColumn: 1
  • msGridColumnSpan: 1

Typography Properties:

  • fontWeight: 1
  • lineHeight: 1

Layout Properties:

  • opacity: 1
  • order: 1
  • orphans: 1
  • scale: 1
  • tabSize: 1
  • widows: 1
  • zIndex: 1
  • zoom: 1

WebKit Properties:

  • WebkitLineClamp: 1

SVG Properties:

  • fillOpacity: 1
  • floodOpacity: 1
  • stopOpacity: 1
  • strokeDasharray: 1
  • strokeDashoffset: 1
  • strokeMiterlimit: 1
  • strokeOpacity: 1
  • strokeWidth: 1

Types

/**
 * Type definition for the unitless object
 * Properties that are unitless map to 1, others are undefined
 */
type UnitlessProperties = Record<string, 1 | undefined>;

Usage Patterns

CSS-in-JS Integration

import unitless from "@emotion/unitless";

function applyStyles(element: HTMLElement, styles: Record<string, number | string>) {
  Object.entries(styles).forEach(([property, value]) => {
    if (typeof value === 'number') {
      // Add units only if the property requires them
      const finalValue = unitless[property] ? value.toString() : `${value}px`;
      element.style.setProperty(property, finalValue);
    } else {
      element.style.setProperty(property, value);
    }
  });
}

// Usage:
applyStyles(myElement, {
  flex: 1,           // Applied as "1"
  opacity: 0.8,      // Applied as "0.8"
  width: 200,        // Applied as "200px"
  height: 100,       // Applied as "100px"
  zIndex: 999        // Applied as "999"
});

Property Validation

import unitless from "@emotion/unitless";

function isUnitlessProperty(property: string): boolean {
  return property in unitless;
}

// Examples:
isUnitlessProperty('flex');        // true
isUnitlessProperty('opacity');     // true
isUnitlessProperty('width');       // false
isUnitlessProperty('margin');      // false

Error Prevention

import unitless from "@emotion/unitless";

function validateNumericStyle(property: string, value: number): void {
  if (!unitless[property] && value !== 0) {
    console.warn(`Property "${property}" with value ${value} may need units`);
  }
}

validateNumericStyle('flex', 1);      // No warning
validateNumericStyle('width', 100);   // Warning: may need units