jQuery jQuery.cssHooks

What You’ll Learn

jQuery.cssHooks lets you plug custom logic into how jQuery reads and writes CSS properties. This tutorial covers the get/set hook shape, vendor-prefix normalization, $.cssNumber, animation via $.fx.step, feature testing, and official jQuery patterns from the API docs.

Introduction

Most of the time, .css() reads computed styles and writes inline properties without you thinking about browser quirks. Plugin authors and advanced developers sometimes need more control — mapping -webkit-border-radius to a single borderRadius name, reading rotation from a transform string, or teaching .animate() to tween a property jQuery does not know natively.

Available since jQuery 1.4.3, jQuery.cssHooks is the extension point behind that flexibility. jQuery ships built-in hooks for properties like opacity and scrollTop. You add entries keyed by camelCase property names; each entry may define get and set functions that jQuery calls whenever code uses .css() or .animate() on that property.

Understanding jQuery.cssHooks

jQuery.cssHooks is a plain object on the jQuery namespace. Keys are CSS property names in camelCase (for example borderRadius, scrollTop). Values are objects with optional get and set functions. When matched elements call .css("borderRadius"), jQuery looks up $.cssHooks.borderRadius.get if it exists; when setting, it calls set.

Think of cssHooks as adapters between jQuery’s uniform API and whatever the browser needs under the hood. Your hook receives the raw DOM element and the value; you decide how to read or write it. Once registered, callers use the normal .css() syntax — hyphenated (border-radius) or camelCase (borderRadius) — and jQuery routes through your adapter.

📝 Syntax

A cssHook is registered by assigning an object to a property name on $.cssHooks:

Hook skeleton (official jQuery template)

(function( $ ) {
  if ( !$.cssHooks ) {
    throw new Error( "jQuery 1.4.3+ is required" );
  }
  $(function () {
    $.cssHooks.someCSSProp = {
      get: function( elem, computed, extra ) {
        // return current value (String or Number)
      },
      set: function( elem, value ) {
        // write value to elem
      }
    };
  });
})( jQuery );

• get(elem, computed, extra) — called when reading .css("someCSSProp"). Return the value jQuery should expose.
• set(elem, value) — called when writing .css("someCSSProp", value). Apply the value to the element.
• Register inside $(function(){ ... }) so jQuery does not overwrite your hook during its own initialization.

Feature test helper (styleSupport)

function styleSupport( prop ) {
  var capProp = prop.charAt( 0 ).toUpperCase() + prop.slice( 1 ),
    prefixes = [ "Moz", "Webkit", "ms" ],
    div = document.createElement( "div" ),
    supportedProp;
  if ( prop in div.style ) {
    supportedProp = prop;
  } else {
    for ( var i = 0; i < prefixes.length; i++ ) {
      var vendorProp = prefixes[ i ] + capProp;
      if ( vendorProp in div.style ) {
        supportedProp = vendorProp;
        break;
      }
    }
  }
  div = null;
  $.support[ prop ] = supportedProp;
  return supportedProp;
}

• Tests standard name first, then vendor-prefixed variants (WebkitBorderRadius, etc.).
• Stores result on $.support[prop] for reuse inside your hook.

Unitless numbers — $.cssNumber

$.cssNumber.someCSSProp = true;

• By default jQuery appends px to numeric setter values for dimension properties.
• Set $.cssNumber.propName = true to keep numbers unitless (opacity, z-index, custom degrees, etc.).

Animation — $.fx.step

$.fx.step.someCSSProp = function( fx ) {
  $.cssHooks.someCSSProp.set( fx.elem, fx.now + fx.unit );
};

• cssHooks alone extend .animate() for many numeric properties.
• Add $.fx.step when the animation engine needs help applying intermediate values each frame.

Return value

• Assigning to $.cssHooks does not return a jQuery object — it is a one-time registration.
• After registration, .css() getters return whatever your get function returns; setters return the jQuery object as usual.

Examples Gallery

Examples 1–5 follow patterns from the official jQuery API documentation. Use the Try-it links to run each snippet in the browser.

$(function () {
  $.cssHooks.borderRadius = {
    get: function( elem ) {
      return $.css( elem, "borderRadius" );
    },
    set: function( elem, value ) {
      elem.style.borderRadius = value;
    }
  };
  $( "#box" ).css( "borderRadius", "16px" );
});

Box corners round to 16px
.css("borderRadius") reads back "16px"


Hook registered inside $(function(){ ... })

function styleSupport( prop ) {
  var capProp = prop.charAt( 0 ).toUpperCase() + prop.slice( 1 ),
    prefixes = [ "Moz", "Webkit", "ms" ],
    div = document.createElement( "div" ),
    supportedProp;
  if ( prop in div.style ) {
    supportedProp = prop;
  } else {
    for ( var i = 0; i < prefixes.length; i++ ) {
      var vendorProp = prefixes[ i ] + capProp;
      if ( vendorProp in div.style ) {
        supportedProp = vendorProp;
        break;
      }
    }
  }
  div = null;
  $.support[ prop ] = supportedProp;
  return supportedProp;
}
styleSupport( "borderRadius" );

Modern browser → "borderRadius"
Legacy WebKit → "WebkitBorderRadius"
Stored on $.support.borderRadius

var borderRadius = styleSupport( "borderRadius" );
if ( borderRadius ) {
  $.cssHooks.borderRadius = {
    get: function( elem ) {
      return $.css( elem, borderRadius );
    },
    set: function( elem, value ) {
      elem.style[ borderRadius ] = value;
    }
  };
}
$( "#a" ).css( "borderRadius", "10px" );
$( "#b" ).css( "border-radius", "20px" );

Box A → 10px radius via borderRadius
Box B → 20px radius via border-radius


Same hook handles both naming styles

$.cssNumber.rotateDeg = true;
$.cssHooks.rotateDeg = {
  get: function( elem ) {
    var m = ( elem.style.transform || "" ).match( /rotate\(([-\d.]+)deg\)/ );
    return m ? parseFloat( m[ 1 ] ) : 0;
  },
  set: function( elem, value ) {
    elem.style.transform = "rotate(" + parseFloat( value ) + "deg)";
  }
};
$( "#box" ).css( "rotateDeg", 45 );

.css("rotateDeg", 45) → box rotates 45°
.css("rotateDeg") getter → 45 (unitless Number)


cssNumber prevents "45px" mistake

$.cssHooks.borderRadius = {
  get: function( elem ) {
    return parseFloat( $.css( elem, "borderRadius" ) ) || 0;
  },
  set: function( elem, value ) {
    elem.style.borderRadius = value + "px";
  }
};
$.fx.step.borderRadius = function( fx ) {
  $.cssHooks.borderRadius.set( fx.elem, fx.now );
};
$( "#box" ).animate({ borderRadius: 40 }, 600 );

Click box → borderRadius animates 0 → 40px over 600ms
Click again → animates back to square


fx.step pushes each frame through cssHooks.set

🚀 Common Use Cases

• Vendor-prefix normalization — map -webkit-border-radius and -moz-border-radius to one borderRadius hook.
• Plugin development — ship a jQuery plugin that adds animatable custom properties without patching core.
• Transform helpers — expose rotateDeg or scaleX as simple numeric cssHook properties.
• Legacy browser support — feature-test once, store on $.support, branch inside get/set.
• Scroll and opacity — study built-in hooks like scrollTop and opacity jQuery already registers.
• Custom tweening — combine cssHooks with $.fx.step for smooth numeric animations.

📝 Notes

• Available since jQuery 1.4.3 — requires $.cssHooks to exist before registering.
• Register hooks inside $(function(){ ... }) — jQuery initializes its own hooks at document ready.
• Property keys use camelCase DOM names (borderRadius, not border-radius).
• Hyphenated names still work at call sites — jQuery normalizes them to the hook key.
• $.cssNumber.prop = true prevents automatic px suffix on numeric setters.
• Built-in hooks include opacity, scrollTop, and scrollLeft — inspect $.cssHooks in DevTools.
• If feature test finds no supported property, skip hook registration — do not throw unless your plugin requires it.

💡 Best Practices