0
# Helper Functions
1

2
Essential utility functions for CSS unit conversion, CSS variables, scaling calculations, and common CSS operations in JavaScript styling solutions.
3

4
## Capabilities
5

6
### Unit Conversion
7

8
Functions for converting between CSS units with context-aware calculations.
9

10
```javascript { .api }
11
/**
12
 * Converts pixel values to rem units based on a context
13
 * @param pxval - Pixel value as string or number
14
 * @param base - Base font size in pixels (default: 16px)
15
 * @returns Converted rem value as string
16
 */
17
function rem(pxval: string | number, base?: string | number): string;
18

19
/**
20
 * Converts pixel values to em units based on a context
21
 * @param pxval - Pixel value as string or number
22
 * @param base - Base font size in pixels (default: 16px)
23
 * @returns Converted em value as string
24
 */
25
function em(pxval: string | number, base?: string | number): string;
26

27
/**
28
 * Converts rem values to pixel values
29
 * @param remval - Rem value as string or number
30
 * @param base - Base font size in pixels (default: 16px)
31
 * @returns Converted pixel value as string
32
 */
33
function remToPx(remval: string | number, base?: string | number): string;
34

35
/**
36
 * Strips the unit from a value, returning just the number
37
 * @param value - CSS value with unit (e.g., "16px", "1.5rem")
38
 * @returns Numeric value without unit
39
 */
40
function stripUnit(value: string): number;
41

42
/**
43
 * Parses a CSS value and returns an array containing the numeric value and unit
44
 * @param value - CSS value string (e.g., "16px", "1.5rem")
45
 * @returns Tuple of [number, unit] where unit may be undefined for unitless values
46
 */
47
function getValueAndUnit(value: string): [number, string | undefined];
48
```
49

50
**Usage Examples:**
51

52
```javascript
53
import { rem, em, stripUnit, getValueAndUnit } from "polished";
54

55
// Unit conversions
56
const fontSize = rem("16px");        // "1rem"
57
const margin = em("24px", "18px");   // "1.33333em" (24px in context of 18px base)
58

59
// Value parsing
60
const numericValue = stripUnit("16px");           // 16
61
const [value, unit] = getValueAndUnit("1.5rem"); // [1.5, "rem"]
62
```
63

64
### CSS Variables and Properties
65

66
Functions for working with CSS custom properties and directional values.
67

68
```javascript { .api }
69
/**
70
 * Fetches the value of a CSS variable in the :root scope, or returns a default value
71
 * @param cssVariable - CSS variable name (with or without -- prefix)
72
 * @param defaultValue - Default value if CSS variable is not found
73
 * @returns CSS variable value or default value
74
 */
75
function cssVar(cssVariable: string, defaultValue?: string | number): string | number;
76

77
/**
78
 * Maps values to directional CSS properties (top, right, bottom, left)
79
 * @param property - CSS property name (e.g., "margin", "padding")
80
 * @param values - 1-4 values following CSS shorthand rules
81
 * @returns Object with directional property assignments
82
 */
83
function directionalProperty(property: string, ...values: Array<?string | ?number>): Styles;
84

85
/**
86
 * Adds !important declaration to a CSS value
87
 * @param value - CSS value to make important
88
 * @returns CSS value with !important declaration
89
 */
90
function important(value: string | number): string;
91
```
92

93
**Usage Examples:**
94

95
```javascript
96
import { cssVar, directionalProperty, important } from "polished";
97

98
// CSS variables with fallbacks
99
const primaryColor = cssVar("--primary-color", "#3498db");
100
const spacing = cssVar("--base-spacing", "16px");
101

102
// Directional properties
103
const margins = directionalProperty("margin", "10px", "20px");
104
// Returns: { marginTop: "10px", marginRight: "20px", marginBottom: "10px", marginLeft: "20px" }
105

106
// Important declarations
107
const criticalStyle = {
108
  color: important("#ff0000"),  // "color: #ff0000 !important"
109
  fontSize: important("18px")   // "font-size: 18px !important"
110
};
111
```
112

113
### Mathematical and Scaling Functions
114

115
Functions for mathematical calculations and modular scaling systems.
116

117
```javascript { .api }
118
/**
119
 * Calculates values on a modular scale
120
 * @param steps - Number of steps up or down the scale (positive or negative integer)
121
 * @param base - Base value for the scale (default: "1rem")
122
 * @param ratio - Scale ratio (default: 1.618, golden ratio)
123
 * @returns Calculated value as string with appropriate unit
124
 */
125
function modularScale(steps: number, base?: string | number, ratio?: number): string;
126
```
127

128
**Usage Examples:**
129

130
```javascript
131
import { modularScale } from "polished";
132

133
// Typography scale using golden ratio
134
const h1Size = modularScale(4);      // Large heading
135
const h2Size = modularScale(3);      // Medium heading  
136
const bodySize = modularScale(0);    // Base size (1rem)
137
const smallSize = modularScale(-1);  // Small text
138

139
// Custom base and ratio
140
const customScale = modularScale(2, "18px", 1.5);  // Custom base and ratio
141

142
// Example scale generation
143
const typeScale = {
144
  h1: modularScale(4, "16px", 1.25),    // ~2.44rem
145
  h2: modularScale(3, "16px", 1.25),    // ~1.95rem
146
  h3: modularScale(2, "16px", 1.25),    // ~1.56rem
147
  body: modularScale(0, "16px", 1.25),  // 1rem
148
  small: modularScale(-1, "16px", 1.25) // ~0.8rem
149
};
150
```
151

152
## Types
153

154
```javascript { .api }
155
interface Styles {
156
  [key: string]: string | number | Styles;
157
}
158
```