jQuery jQuery.cssNumber

What You’ll Learn

jQuery.cssNumber lists CSS properties that do not need units. Before jQuery 4.0, .css() used this object to decide whether to append px to numeric setter values. This tutorial covers built-in keys, adding custom entries, pairing with cssHooks, and migration notes.

Introduction

When you write $("#box").css("width", 200), jQuery turns 200 into 200px because width is a pixel dimension. When you write $("#box").css("opacity", 0.5), jQuery leaves 0.5 alone — opacity is unitless. That distinction comes from jQuery.cssNumber.

Available since jQuery 1.4.3, cssNumber is a lookup object: camelCase property names mapped to true. Prior to jQuery 4.0, the .css() setter consulted this list before auto-appending px. Plugin authors also add custom keys when pairing cssHooks with synthetic unitless properties. jQuery 4.0 removed the API — pass explicit unit strings instead.

Understanding jQuery.cssNumber

jQuery.cssNumber is a plain object on the jQuery namespace. Each key is a CSS property name in camelCase (opacity, zIndex, lineHeight); each value is true, meaning “this property accepts unitless numeric values.” It is not a function — you read and extend the object directly.

Think of it as an allowlist for bare numbers. Properties not on the list — like width, height, marginTop — get px appended when you pass a number to .css(). Properties on the list keep the number as-is. That prevents invalid values like opacity: 0.5px or z-index: 10px.

📝 Syntax

jQuery.cssNumber is an object — there is no function call syntax:

Read a built-in entry

jQuery.cssNumber.opacity   // true
jQuery.cssNumber.zIndex    // true
jQuery.cssNumber.width     // undefined (not unitless)

Add a custom property (official jQuery pattern)

if ( jQuery.cssNumber ) {
  jQuery.cssNumber.someCSSProp = true;
}

• Guard with if ( jQuery.cssNumber ) — the object does not exist in jQuery 4.0+.
• Use camelCase keys matching DOM style property names.
• Pair with a matching $.cssHooks.someCSSProp entry when the property is custom.

Effect on .css() numeric setters (jQuery < 4.0)

$( "#a" ).css( "width", 200 );     // → width: 200px
$( "#b" ).css( "opacity", 0.5 );   // → opacity: 0.5
$( "#c" ).css( "zIndex", 10 );     // → z-index: 10

Built-in properties (selected)

• Core — opacity, zIndex, lineHeight, fontWeight, zoom (since 1.4.3)
• Layout — flexGrow, flexShrink, order, columnCount, orphans, widows
• Modern — aspectRatio, scale, animationIterationCount, grid properties (3.4+ / 3.7+)
• SVG — fillOpacity, strokeOpacity, stopOpacity, and related keys

Return value

• jQuery.cssNumber itself is the object — assigning a property returns the assigned value (true).
• Reading a missing key returns undefined — jQuery then applies default px logic for numeric setters.

Examples Gallery

Examples 1–5 demonstrate built-in unitless properties, px auto-append behavior, and adding custom keys. Use the Try-it links to run each snippet.

$( "#box" ).css( "opacity", 0.5 );
// inline style: opacity: 0.5  (NOT 0.5px)

Box fades to 50% opacity
Inline style: opacity: 0.5


jQuery.cssNumber.opacity === true

$( "#overlay" ).css( "zIndex", 100 );
// inline style: z-index: 100  (NOT 100px)

Green layer moves above red
z-index: 100 — no unit suffix


zIndex in cssNumber since 1.4.3

$( "#text" ).css( "lineHeight", 1.5 );
// equivalent to 1.5 × current font-size

lineHeight: 1.2 → tighter text
lineHeight: 2   → looser text


Unitless multiplier — not 1.5px

$( "#box" ).css( "width", 200 );    // → width: 200px
$( "#box" ).css( "opacity", 0.4 );  // → opacity: 0.4

// width is NOT in $.cssNumber
// opacity IS in $.cssNumber

width 200   → style="width: 200px;"
opacity 0.4 → style="opacity: 0.4;"


cssNumber is the allowlist jQuery checks

if ( jQuery.cssNumber ) {
  jQuery.cssNumber.rotateDeg = true;
}
jQuery.cssHooks.rotateDeg = {
  set: function( elem, value ) {
    elem.style.transform = "rotate(" + parseFloat( value ) + "deg)";
  }
};
$( "#box" ).css( "rotateDeg", 90 );

Box rotates 90°
.css("rotateDeg", 90) passes 90 — not "90px"


Official guard: if (jQuery.cssNumber) { ... }

🚀 Common Use Cases

• Fade effects — .css("opacity", 0) and .animate({ opacity: 1 }) rely on cssNumber.
• Modal overlays — .css("zIndex", 9999) to stack above page content.
• Typography — .css("lineHeight", 1.6) for readable unitless spacing.
• Flexbox order — .css("order", 2) and .css("flexGrow", 1) without units.
• Plugin cssHooks — add custom keys so numeric setters reach your hook correctly.
• Debugging px bugs — if a numeric setter produces px unexpectedly, check whether the property is in cssNumber.

📝 Notes

• Available since jQuery 1.4.3 — removed in jQuery 4.0.
• Keys are camelCase DOM property names; all values are true.
• Only affects numeric setter values — strings like "200px" or "50%" pass through unchanged.
• Guard custom additions: if ( jQuery.cssNumber ) { ... }.
• jQuery 4.0+: pass explicit unit strings to .css() — no auto px append at all.
• Pairs naturally with cssHooks for custom animatable properties.
• Inspect the full list in DevTools: Object.keys($.cssNumber) (jQuery 3.x).

💡 Best Practices