0
# Math Functions
1

2
CSS unit-aware mathematical calculations with support for complex formulas, mixed units, and mathematical operations designed for responsive design and design systems.
3

4
## Capabilities
5

6
### Mathematical Formula Evaluation
7

8
Function for performing mathematical calculations with CSS units and values.
9

10
```javascript { .api }
11
/**
12
 * Helper for doing math with CSS units. Accepts a formula as a string and evaluates it.
13
 * @param formula - Mathematical formula as string with CSS units
14
 * @param additionalSymbols - Optional object with additional variables/symbols
15
 * @returns Calculated result as string with appropriate unit
16
 */
17
function math(formula: string, additionalSymbols?: Object): string;
18
```
19

20
## Supported Operations
21

22
The `math` function supports the following mathematical operations:
23

24
- **Addition**: `+`
25
- **Subtraction**: `-`  
26
- **Multiplication**: `*`
27
- **Division**: `/`
28
- **Square root**: `sqrt()`
29
- **Power/Exponentiation**: `^` or `pow()`
30
- **Factorial**: `!`
31
- **Minimum**: `min()`
32
- **Maximum**: `max()`
33
- **Parentheses**: `()` for grouping
34

35
## Supported CSS Units
36

37
The math function can work with any CSS unit:
38

39
- **Absolute units**: `px`, `pt`, `pc`, `in`, `cm`, `mm`
40
- **Relative units**: `em`, `rem`, `ex`, `ch`, `vh`, `vw`, `vmin`, `vmax`
41
- **Percentage**: `%`
42
- **Unitless values**: Numbers without units
43

44
## Usage Examples
45

46
### Basic Calculations
47

48
```javascript
49
import { math } from "polished";
50

51
// Simple arithmetic with units
52
const width = math("100px + 50px");           // "150px"
53
const height = math("100vh - 80px");          // "calc(100vh - 80px)"
54
const fontSize = math("16px * 1.5");          // "24px"
55
const margin = math("40px / 2");              // "20px"
56

57
// Mixed unit calculations (automatically uses calc())
58
const responsiveWidth = math("50% + 20px");   // "calc(50% + 20px)"
59
const fluidHeight = math("100vh - 3rem");     // "calc(100vh - 3rem)"
60
```
61

62
### Complex Formulas
63

64
```javascript
65
import { math } from "polished";
66

67
// Responsive grid calculations
68
const columnWidth = math("(100% - 60px) / 4");        // "calc((100% - 60px) / 4)"
69
const gutterSize = math("20px * 1.5");                // "30px"
70

71
// Typography calculations
72
const lineHeightCalc = math("24px * 1.4");            // "33.6px"
73
const typeScale = math("16px * pow(1.25, 3)");        // "31.25px"
74

75
// Layout spacing calculations
76
const containerPadding = math("max(20px, 5vw)");      // "max(20px, 5vw)"
77
const verticalRhythm = math("24px * 2 + 16px");       // "64px"
78

79
// Advanced mathematical operations
80
const goldenRatio = math("(1 + sqrt(5)) / 2");        // "1.618033988749895"
81
const circleArea = math("pow(10px, 2) * 3.14159");    // "314.159px"
82
```
83

84
### Custom Variables and Symbols
85

86
```javascript
87
import { math } from "polished";
88

89
// Define custom variables
90
const designTokens = {
91
  baseFont: "16px",
92
  baseSpacing: "8px",
93
  ratio: 1.25
94
};
95

96
// Use custom variables in calculations
97
const headingSize = math("baseFont * pow(ratio, 3)", designTokens);    // "31.25px"
98
const largeSpacing = math("baseSpacing * 4", designTokens);            // "32px"
99
const responsiveFont = math("baseFont + 2vw", designTokens);           // "calc(16px + 2vw)"
100

101
// Complex design system calculations
102
const modularSpacing = math("baseSpacing * pow(2, 3)", designTokens);  // "64px"
103
const fluidType = math("baseFont + (24px - baseFont) * (100vw - 320px) / (1200px - 320px)", designTokens);
104
```
105

106
### Responsive Design Patterns
107

108
```javascript
109
import { math } from "polished";
110

111
// Fluid grid system
112
const createFluidGrid = (columns, gap = "20px") => ({
113
  width: math(`(100% - ${gap} * ${columns - 1}) / ${columns}`),
114
  marginRight: gap,
115
  "&:nth-child(${columns}n)": {
116
    marginRight: 0
117
  }
118
});
119

120
// Responsive container widths
121
const containerSizes = {
122
  small: math("min(90%, 600px)"),      // "min(90%, 600px)"
123
  medium: math("min(85%, 900px)"),     // "min(85%, 900px)"
124
  large: math("min(80%, 1200px)")      // "min(80%, 1200px)"
125
};
126

127
// Aspect ratio calculations
128
const aspectRatio = (width, height) => ({
129
  width: "100%",
130
  height: 0,
131
  paddingBottom: math(`${height} / ${width} * 100%`)
132
});
133

134
// Usage
135
const videoAspect = aspectRatio("16", "9");  // 16:9 aspect ratio
136
```
137

138
### Design System Integration
139

140
```javascript
141
import { math } from "polished";
142

143
// Spacing scale based on mathematical progression
144
const spacingScale = {
145
  xs: math("4px * 1"),         // "4px"
146
  sm: math("4px * 2"),         // "8px"  
147
  md: math("4px * 4"),         // "16px"
148
  lg: math("4px * 6"),         // "24px"
149
  xl: math("4px * 8"),         // "32px"
150
  xxl: math("4px * 12")        // "48px"
151
};
152

153
// Typography scale with mathematical ratios
154
const createTypeScale = (baseSize = "16px", ratio = 1.25) => {
155
  const symbols = { base: baseSize, r: ratio };
156
  
157
  return {
158
    xs: math("base / pow(r, 1)", symbols),    // Smaller text
159
    sm: math("base / pow(r, 0.5)", symbols),  // Small text
160
    base: math("base", symbols),              // Base text
161
    lg: math("base * pow(r, 1)", symbols),   // Large text
162
    xl: math("base * pow(r, 2)", symbols),   // Extra large text
163
    xxl: math("base * pow(r, 3)", symbols)   // Heading text
164
  };
165
};
166

167
// Border radius scale
168
const borderRadiusScale = {
169
  sm: math("2px * 1"),         // "2px"
170
  md: math("2px * 2"),         // "4px"
171
  lg: math("2px * 4"),         // "8px"
172
  xl: math("2px * 6"),         // "12px"
173
  full: "50%"
174
};
175
```
176

177
## Error Handling
178

179
The `math` function will:
180
- Return CSS `calc()` expressions when mixing incompatible units
181
- Preserve units when performing operations on compatible units
182
- Handle division by zero gracefully
183
- Maintain precision for decimal calculations
184

185
```javascript
186
import { math } from "polished";
187

188
// Compatible units are calculated directly
189
const samePx = math("100px + 50px");           // "150px"
190

191
// Incompatible units use calc()
192
const mixedUnits = math("50% + 100px");        // "calc(50% + 100px)"
193

194
// Complex expressions with calc()
195
const complexCalc = math("(100vw - 40px) / 3 + 2rem");  // "calc((100vw - 40px) / 3 + 2rem)"
196
```