Core utility functions for converting between px, rem, and em units, ensuring consistent sizing across different contexts and maintaining accessibility standards.
Default font size used for all unit conversions.
/**
* Base font size used for unit conversions
*/
const baseFontSize: number; // 16Converts pixel values to rem units based on the base font size.
/**
* Convert a given px unit to a rem unit
* @param px - Pixel value to convert
* @returns String with rem unit
*/
function rem(px: number): string;Usage Examples:
import { rem } from '@carbon/layout';
const headerHeight = rem(64); // "4rem"
const buttonPadding = rem(12); // "0.75rem"
const iconSize = rem(24); // "1.5rem"Converts pixel values to em units based on the base font size.
/**
* Convert a given px unit to a em unit
* @param px - Pixel value to convert
* @returns String with em unit
*/
function em(px: number): string;Usage Examples:
import { em } from '@carbon/layout';
const fontSize = em(18); // "1.125em"
const lineHeight = em(24); // "1.5em"
const letterSpacing = em(1); // "0.0625em"Converts numeric values to pixel strings.
/**
* Convert a given px unit to its string representation
* @param value - Number of pixels
* @returns String with px unit
*/
function px(value: number): string;Usage Examples:
import { px } from '@carbon/layout';
const borderWidth = px(2); // "2px"
const shadowOffset = px(4); // "4px"
const borderRadius = px(8); // "8px"The SCSS API provides equivalent functionality with additional error checking and the option to use the newer to-rem function.
/// Default font size
/// @type Number
$base-font-size: 16px !default;
/// Convert a given px unit to a rem unit
/// @param {Number} $px - Number with px unit
/// @return {Number} Number with rem unit
@function to-rem($px);
/// Legacy rem conversion function (deprecated)
/// @param {Number} $px - Number with px unit
/// @return {Number} Number with rem unit
/// @deprecated Use to-rem instead
@function rem($px);
/// Convert a given px unit to a em unit
/// @param {Number} $px - Number with px unit
/// @return {Number} Number with em unit
@function em($px);SCSS Usage Examples:
@use '@carbon/layout/scss/convert' as convert;
.component {
height: convert.to-rem(64px); // 4rem
padding: convert.to-rem(16px); // 1rem
font-size: convert.em(14px); // 0.875em
// Legacy function (deprecated)
margin: convert.rem(8px); // 0.5rem
}Common pixel to rem conversions at 16px base font size:
| Pixels | Rem | Em | Common Use Case |
|---|---|---|---|
| 2px | 0.125rem | 0.125em | Border width |
| 4px | 0.25rem | 0.25em | Small spacing |
| 8px | 0.5rem | 0.5em | Mini unit |
| 12px | 0.75rem | 0.75em | Small padding |
| 16px | 1rem | 1em | Base font size |
| 20px | 1.25rem | 1.25em | Icon size |
| 24px | 1.5rem | 1.5em | Medium spacing |
| 32px | 2rem | 2em | Large spacing |
| 48px | 3rem | 3em | Component height |
| 64px | 4rem | 4em | Header height |
The SCSS functions include type checking and will throw errors for invalid input:
// This will cause an error
.invalid {
height: convert.to-rem(64); // Error: Expected px unit, got number
padding: convert.to-rem("16px"); // Error: Expected number, got string
}
// Correct usage
.valid {
height: convert.to-rem(64px); // ✓ 4rem
padding: convert.to-rem(16px); // ✓ 1rem
}