0
# MUI System
1

2
MUI System is a comprehensive CSS-in-JS utility system for React applications that enables rapid custom design implementation through composable style functions, responsive design utilities, and theme-aware styling. It provides a systematic approach to styling with functions for spacing, colors, typography, flexbox, grid, borders, and other CSS properties that can be applied directly to components through props.
3

4
## Package Information
5

6
- **Package Name**: @mui/system
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install @mui/system`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  Box, 
16
  Container, 
17
  Grid, 
18
  Stack,
19
  createTheme, 
20
  ThemeProvider, 
21
  useTheme,
22
  styled
23
} from "@mui/system";
24
```
25

26
For CommonJS:
27

28
```javascript
29
const { 
30
  Box, 
31
  Container, 
32
  Grid, 
33
  Stack,
34
  createTheme, 
35
  ThemeProvider, 
36
  useTheme,
37
  styled 
38
} = require("@mui/system");
39
```
40

41
## Basic Usage
42

43
```typescript
44
import { Box, createTheme, ThemeProvider } from "@mui/system";
45

46
// Create a theme
47
const theme = createTheme({
48
  palette: {
49
    primary: {
50
      main: '#1976d2',
51
    },
52
  },
53
  spacing: 8,
54
});
55

56
// Use with Box component
57
function App() {
58
  return (
59
    <ThemeProvider theme={theme}>
60
      <Box
61
        sx={{
62
          width: { xs: '100%', sm: '50%' },
63
          p: 2,
64
          backgroundColor: 'primary.main',
65
          color: 'white',
66
        }}
67
      >
68
        <Box mt={2} mb={1}>
69
          Hello World
70
        </Box>
71
      </Box>
72
    </ThemeProvider>
73
  );
74
}
75
```
76

77
## Architecture
78

79
MUI System is built around several key architectural concepts:
80

81
- **System Props**: Direct CSS-like props that accept theme-aware values and responsive breakpoints
82
- **sx Prop**: Advanced styling prop that supports theme access, responsive values, and pseudo-selectors
83
- **Theme-Aware Values**: All styling props can reference theme values (colors, spacing, breakpoints)
84
- **Responsive Design**: Values can be objects with breakpoint keys for responsive behavior
85
- **Composable Functions**: Style functions can be composed together for reusable styling patterns
86
- **CSS-in-JS Integration**: Seamless integration with emotion and styled-components
87

88
## Capabilities
89

90
### Layout Components
91

92
Core React components for building layouts with system props support and responsive design capabilities.
93

94
```typescript { .api }
95
// Box - Universal container with all system props
96
interface BoxProps<Theme = Theme> extends SystemProps<Theme> {
97
  children?: React.ReactNode;
98
  sx?: SxProps<Theme>;
99
  component?: React.ElementType;
100
}
101

102
// Container - Responsive container with max-width constraints
103
interface ContainerProps<Theme = Theme> {
104
  maxWidth?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | false;
105
  fixed?: boolean;
106
  disableGutters?: boolean;
107
  sx?: SxProps<Theme>;
108
}
109

110
// Grid - Modern CSS Grid layout system
111
interface GridProps<Theme = Theme> {
112
  container?: boolean;
113
  size?: GridSize | ResponsiveStyleValue<GridSize>;
114
  offset?: GridOffset | ResponsiveStyleValue<GridOffset>;
115
  spacing?: GridSpacing | ResponsiveStyleValue<GridSpacing>;
116
  columns?: number | ResponsiveStyleValue<number>;
117
  sx?: SxProps<Theme>;
118
}
119

120
// Stack - One-dimensional layout with spacing
121
interface StackProps<Theme = Theme> {
122
  direction?: 'row' | 'column' | ResponsiveStyleValue<'row' | 'column'>;
123
  spacing?: number | string | ResponsiveStyleValue<number | string>;
124
  divider?: React.ReactNode;
125
  useFlexGap?: boolean;
126
  sx?: SxProps<Theme>;
127
}
128
```
129

130
[Layout Components](./components.md)
131

132
### Theme System
133

134
Complete theming system for creating consistent design tokens, providing theme context, and accessing theme values in components.
135

136
```typescript { .api }
137
function createTheme(options?: ThemeOptions, ...args: object[]): Theme;
138

139
interface Theme extends CssContainerQueries {
140
  breakpoints: Breakpoints;
141
  spacing: Spacing;
142
  palette: Record<string, any> & { mode: 'light' | 'dark' };
143
  typography?: Typography;
144
  shadows?: Shadows;
145
  shape: Shape;
146
  direction: Direction;
147
  mixins?: Mixins;
148
  transitions?: Transitions;
149
  zIndex?: ZIndex;
150
  components?: Record<string, any>;
151
  applyStyles: ApplyStyles<'light' | 'dark'>;
152
  unstable_sx: (props: SxProps<Theme>) => CSSObject;
153
  unstable_sxConfig: SxConfig;
154
}
155

156
function useTheme<T = Theme>(defaultTheme?: T): T;
157
```
158

159
[Theme System](./theme-system.md)
160

161
### Style Functions
162

163
Composable style functions that transform component props into CSS properties with theme integration and responsive support.
164

165
```typescript { .api }
166
// Core style function types
167
type StyleFunction<Props> = (props: Props) => CSSObject;
168
type ResponsiveStyleValue<T> = T | { [key in Breakpoint]?: T };
169

170
// Main style function categories
171
const spacing: StyleFunction<SpacingProps>;
172
const typography: StyleFunction<TypographyProps>;
173
const borders: StyleFunction<BordersProps>;
174
const palette: StyleFunction<PaletteProps>;
175
const sizing: StyleFunction<SizingProps>;
176
const flexbox: StyleFunction<FlexboxProps>;
177
const grid: StyleFunction<CssGridProps>;
178
const positions: StyleFunction<PositionsProps>;
179
const display: StyleFunction<DisplayProps>;
180
const shadows: StyleFunction<ShadowsProps>;
181
```
182

183
[Style Functions](./style-functions.md)
184

185
### Utilities
186

187
Color manipulation, breakpoint handling, and other utility functions for advanced theming and responsive design.
188

189
```typescript { .api }
190
// Color manipulation utilities
191
function alpha(color: string, value: number): string;
192
function darken(color: string, coefficient: number): string;
193
function lighten(color: string, coefficient: number): string;
194
function getContrastRatio(foreground: string, background: string): number;
195

196
// Breakpoint utilities
197
function createBreakpoints(options: BreakpointsOptions): Breakpoints;
198
function handleBreakpoints<T>(prop: T, transform: (value: any) => any): any;
199

200
// Spacing utilities
201
function createSpacing(spacingInput: SpacingOptions): Spacing;
202
```
203

204
[Utilities](./utilities.md)
205

206
### CSS-in-JS Integration
207

208
Styled component creation, CSS utilities, and advanced styling patterns with full theme integration.
209

210
```typescript { .api }
211
function styled<Component extends React.ComponentType<any>>(
212
  component: Component
213
): CreateMUIStyled;
214

215
function createStyled<Theme extends object = Theme>(
216
  options?: StyledOptions<Theme>
217
): CreateMUIStyled<Theme>;
218

219
// CSS utilities from styled-engine
220
function css(template: TemplateStringsArray, ...args: any[]): CSSInterpolation;
221
function keyframes(template: TemplateStringsArray, ...args: any[]): Keyframes;
222

223
// Global styles
224
interface GlobalStylesProps<Theme = Theme> {
225
  styles: CSSInterpolation | ((theme: Theme) => CSSInterpolation);
226
  defaultTheme?: Theme;
227
  themeId?: string;
228
}
229
```
230

231
[CSS-in-JS Integration](./css-in-js.md)
232

233
## Common Types
234

235
```typescript { .api }
236
// Responsive value wrapper
237
type ResponsiveStyleValue<T> = T | Partial<Record<Breakpoint, T>>;
238

239
// System props (all CSS properties with theme support)
240
interface SystemProps<Theme = Theme> {
241
  // Spacing
242
  m?: ResponsiveStyleValue<number | string>;
243
  p?: ResponsiveStyleValue<number | string>;
244
  
245
  // Colors  
246
  color?: ResponsiveStyleValue<string>;
247
  bgcolor?: ResponsiveStyleValue<string>;
248
  
249
  // Typography
250
  fontSize?: ResponsiveStyleValue<number | string>;
251
  fontWeight?: ResponsiveStyleValue<number | string>;
252
  
253
  // Layout
254
  width?: ResponsiveStyleValue<number | string>;
255
  height?: ResponsiveStyleValue<number | string>;
256
  display?: ResponsiveStyleValue<string>;
257
  
258
  // And 100+ more CSS properties...
259
}
260

261
// sx prop type
262
interface SxProps<Theme = Theme> {
263
  [key: string]: 
264
    | SystemStyleObject<Theme>
265
    | ResponsiveStyleValue<SystemStyleObject<Theme>>
266
    | ((theme: Theme) => SystemStyleObject<Theme>);
267
}
268

269
// Breakpoint keys (extensible via module augmentation)
270
type Breakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
271

272
// Grid specific types  
273
type GridSize = 'auto' | 'grow' | number | false;
274
type GridOffset = 'auto' | number;
275
type GridSpacing = number | string;
276

277
// Color object structure
278
interface ColorObject {
279
  type: ColorFormat;
280
  values: number[];
281
  colorSpace?: string;
282
}
283

284
type ColorFormat = 'rgb' | 'rgba' | 'hsl' | 'hsla' | 'color';
285
```