0
# Material-UI Core
1

2
Material-UI Core is a comprehensive React component library that implements Google's Material Design specification. It provides over 100 customizable components including buttons, forms, navigation, layout, and data display elements with a powerful theming system and CSS-in-JS styling solution.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { Button, TextField, AppBar, Typography } from "@material-ui/core";
15
import { createMuiTheme, ThemeProvider } from "@material-ui/core/styles";
16
import * as colors from "@material-ui/core/colors";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const { Button, TextField, AppBar, Typography } = require("@material-ui/core");
23
const { createMuiTheme, ThemeProvider } = require("@material-ui/core/styles");
24
const colors = require("@material-ui/core/colors");
25
```
26

27
## Basic Usage
28

29
```typescript
30
import React from 'react';
31
import { Button, TextField, Paper, Typography } from '@material-ui/core';
32
import { createMuiTheme, ThemeProvider } from '@material-ui/core/styles';
33
import { blue } from '@material-ui/core/colors';
34

35
// Create custom theme
36
const theme = createMuiTheme({
37
  palette: {
38
    primary: blue,
39
  },
40
});
41

42
function App() {
43
  return (
44
    <ThemeProvider theme={theme}>
45
      <Paper style={{ padding: 16 }}>
46
        <Typography variant="h4" gutterBottom>
47
          Welcome to Material-UI
48
        </Typography>
49
        <TextField
50
          label="Enter your name"
51
          variant="outlined"
52
          fullWidth
53
          margin="normal"
54
        />
55
        <Button variant="contained" color="primary">
56
          Submit
57
        </Button>
58
      </Paper>
59
    </ThemeProvider>
60
  );
61
}
62
```
63

64
## Architecture
65

66
Material-UI Core is built around several key architectural principles:
67

68
- **Component System**: All components extend a base component system with consistent props interface (`className`, `style`, `classes`, `component`)
69
- **Theming**: Centralized theme configuration with `createMuiTheme` and `ThemeProvider` for colors, typography, spacing, and breakpoints
70
- **CSS-in-JS**: Built on JSS with `withStyles` HOC for component styling and customization
71
- **Material Design**: Faithful implementation of Material Design guidelines with proper elevation, motion, and interaction patterns
72
- **Accessibility**: WCAG-compliant components with proper ARIA attributes and keyboard navigation
73
- **TypeScript**: Full TypeScript support with detailed prop interfaces and generic components
74

75
## Capabilities
76

77
### Theming and Styling
78

79
Complete theming system with custom theme creation, styling utilities, and CSS-in-JS integration for consistent design across applications.
80

81
```typescript { .api }
82
function createMuiTheme(options?: ThemeOptions): Theme;
83
function withStyles<P extends object>(
84
  styles: Styles<Theme, P>,
85
  options?: WithStylesOptions<Theme>
86
): (Component: React.ComponentType<P>) => React.ComponentType<P>;
87
function withTheme<P extends WithThemeProps<Theme>>(
88
  Component: React.ComponentType<P>
89
): React.ComponentType<Omit<P, keyof WithThemeProps<Theme>>>;
90

91
interface Theme {
92
  palette: Palette;
93
  typography: Typography;
94
  spacing: Spacing;
95
  breakpoints: Breakpoints;
96
  shadows: Shadows;
97
  transitions: Transitions;
98
  zIndex: ZIndex;
99
  shape: Shape;
100
}
101
```
102

103
[Theming and Styling](./theming-styling.md)
104

105
### Layout Components
106

107
Structural components for creating responsive layouts including app bars, grids, containers, and surfaces.
108

109
```typescript { .api }
110
function AppBar(props: AppBarProps): JSX.Element;
111
function Grid(props: GridProps): JSX.Element;
112
function Paper(props: PaperProps): JSX.Element;
113
function Toolbar(props: ToolbarProps): JSX.Element;
114

115
interface GridProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>, GridClassKey> {
116
  container?: boolean;
117
  item?: boolean;
118
  xs?: boolean | GridSize;
119
  sm?: boolean | GridSize;
120
  md?: boolean | GridSize;
121
  lg?: boolean | GridSize;
122
  xl?: boolean | GridSize;
123
  spacing?: GridSpacing;
124
  direction?: GridDirection;
125
  justify?: GridJustification;
126
  alignItems?: GridItemsAlignment;
127
  alignContent?: GridContentAlignment;
128
  wrap?: GridWrap;
129
}
130
```
131

132
[Layout Components](./layout.md)
133

134
### Input Components
135

136
Form controls and interactive elements including buttons, text fields, selects, checkboxes, and other input components.
137

138
```typescript { .api }
139
function Button(props: ButtonProps): JSX.Element;
140
function IconButton(props: IconButtonProps): JSX.Element;
141
function TextField(props: TextFieldProps): JSX.Element;
142
function InputAdornment(props: InputAdornmentProps): JSX.Element;
143
function InputLabel(props: InputLabelProps): JSX.Element;
144
function Checkbox(props: CheckboxProps): JSX.Element;
145
function Select(props: SelectProps): JSX.Element;
146

147
interface ButtonProps extends StandardProps<ButtonBaseProps, ButtonClassKey> {
148
  children: React.ReactNode;
149
  color?: 'default' | 'inherit' | 'primary' | 'secondary';
150
  variant?: 'text' | 'outlined' | 'contained' | 'fab' | 'extendedFab';
151
  size?: 'small' | 'medium' | 'large';
152
  disabled?: boolean;
153
  disableElevation?: boolean;
154
  disableFocusRipple?: boolean;
155
  disableRipple?: boolean;
156
  endIcon?: React.ReactNode;
157
  startIcon?: React.ReactNode;
158
  fullWidth?: boolean;
159
  href?: string;
160
}
161

162
interface IconButtonProps extends StandardProps<ButtonBaseProps, IconButtonClassKey> {
163
  children: React.ReactNode;
164
  color?: 'default' | 'inherit' | 'primary' | 'secondary';
165
  disabled?: boolean;
166
  disableRipple?: boolean;
167
  size?: 'small' | 'medium';
168
}
169
```
170

171
[Input Components](./inputs.md)
172

173
### Navigation Components
174

175
Navigation-related components including menus, tabs, steppers, and navigation drawers.
176

177
```typescript { .api }
178
function Menu(props: MenuProps): JSX.Element;
179
function Tabs(props: TabsProps): JSX.Element;
180
function Drawer(props: DrawerProps): JSX.Element;
181
function Stepper(props: StepperProps): JSX.Element;
182

183
interface DrawerProps extends StandardProps<ModalProps, DrawerClassKey> {
184
  anchor?: 'left' | 'top' | 'right' | 'bottom';
185
  children?: React.ReactNode;
186
  elevation?: number;
187
  open?: boolean;
188
  variant?: 'permanent' | 'persistent' | 'temporary';
189
}
190
```
191

192
[Navigation Components](./navigation.md)
193

194
### Data Display Components
195

196
Components for displaying data including tables, lists, cards, typography, and icons.
197

198
```typescript { .api }
199
function Table(props: TableProps): JSX.Element;
200
function List(props: ListProps): JSX.Element;
201
function Card(props: CardProps): JSX.Element;
202
function Typography(props: TypographyProps): JSX.Element;
203

204
interface TypographyProps extends StandardProps<React.HTMLAttributes<HTMLElement>, TypographyClassKey> {
205
  align?: 'inherit' | 'left' | 'center' | 'right' | 'justify';
206
  children?: React.ReactNode;
207
  color?: 'inherit' | 'primary' | 'secondary' | 'textPrimary' | 'textSecondary' | 'error';
208
  component?: React.ElementType;
209
  gutterBottom?: boolean;
210
  noWrap?: boolean;
211
  paragraph?: boolean;
212
  variant?: TypographyVariant;
213
}
214
```
215

216
[Data Display Components](./data-display.md)
217

218
### Feedback Components
219

220
User feedback components including progress indicators, dialogs, snackbars, and tooltips.
221

222
```typescript { .api }
223
function Dialog(props: DialogProps): JSX.Element;
224
function CircularProgress(props: CircularProgressProps): JSX.Element;
225
function Snackbar(props: SnackbarProps): JSX.Element;
226
function Tooltip(props: TooltipProps): JSX.Element;
227

228
interface DialogProps extends StandardProps<ModalProps, DialogClassKey> {
229
  children?: React.ReactNode;
230
  fullScreen?: boolean;
231
  fullWidth?: boolean;
232
  maxWidth?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | false;
233
  scroll?: 'body' | 'paper';
234
  TransitionComponent?: React.ComponentType<TransitionProps>;
235
  transitionDuration?: TransitionProps['timeout'];
236
}
237
```
238

239
[Feedback Components](./feedback.md)
240

241
### Utility Components
242

243
Utility components and higher-order components for common functionality like portals, transitions, and responsive behavior.
244

245
```typescript { .api }
246
function Portal(props: PortalProps): React.ReactPortal | null;
247
function ClickAwayListener(props: ClickAwayListenerProps): JSX.Element;
248
function Hidden(props: HiddenProps): JSX.Element;
249
function withMobileDialog<P>(options?: WithMobileDialogOptions): (Component: React.ComponentType<P>) => React.ComponentType<P>;
250
function withWidth<P extends WithWidthProps>(options?: WithWidthOptions): (Component: React.ComponentType<P>) => React.ComponentType<P>;
251

252
interface HiddenProps {
253
  children: React.ReactNode;
254
  implementation?: 'js' | 'css';
255
  initialWidth?: Breakpoint;
256
  lgDown?: boolean;
257
  lgUp?: boolean;
258
  mdDown?: boolean;
259
  mdUp?: boolean;
260
  only?: Breakpoint | Breakpoint[];
261
  smDown?: boolean;
262
  smUp?: boolean;
263
  xlDown?: boolean;
264
  xlUp?: boolean;
265
  xsDown?: boolean;
266
  xsUp?: boolean;
267
}
268
```
269

270
[Utility Components](./utilities.md)
271

272
### Color System
273

274
Complete Material Design color palette with all color variants and accessibility-friendly combinations.
275

276
```typescript { .api }
277
interface Color {
278
  50: string;
279
  100: string;
280
  200: string;
281
  300: string;
282
  400: string;
283
  500: string;
284
  600: string;
285
  700: string;
286
  800: string;
287
  900: string;
288
  A100: string;
289
  A200: string;
290
  A400: string;
291
  A700: string;
292
}
293

294
const red: Color;
295
const pink: Color;
296
const purple: Color;
297
const deepPurple: Color;
298
const indigo: Color;
299
const blue: Color;
300
const lightBlue: Color;
301
const cyan: Color;
302
const teal: Color;
303
const green: Color;
304
const lightGreen: Color;
305
const lime: Color;
306
const yellow: Color;
307
const amber: Color;
308
const orange: Color;
309
const deepOrange: Color;
310
const brown: Color;
311
const grey: Color;
312
const blueGrey: Color;
313
const common: {
314
  black: string;
315
  white: string;
316
};
317
```
318

319
[Color System](./colors.md)
320

321
## Types
322

323
```typescript { .api }
324
type StandardProps<C, ClassKey extends string, Removals extends keyof C = never> = Omit<
325
  C,
326
  'classes' | Removals
327
> & StyledComponentProps<ClassKey> & {
328
  className?: string;
329
  style?: React.CSSProperties;
330
};
331

332
interface StyledComponentProps<ClassKey extends string = string> {
333
  classes?: Partial<ClassesNameMap<ClassKey>>;
334
}
335

336
type PropsOf<C> = C extends new (props: infer P) => React.Component
337
  ? P
338
  : C extends (props: infer P) => React.ReactElement<any> | null
339
  ? P
340
  : C extends keyof JSX.IntrinsicElements
341
  ? JSX.IntrinsicElements[C]
342
  : never;
343

344
type PaletteType = 'light' | 'dark';
345

346
type Breakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
347
type GridSize = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
348
type GridSpacing = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10;
349
type TypographyVariant = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 
350
  'subtitle1' | 'subtitle2' | 'body1' | 'body2' | 'caption' | 'button' | 'overline';
351
```