0
# @rjsf/material-ui
1

2
@rjsf/material-ui provides comprehensive Material UI theme integration for react-jsonschema-form, offering both Material UI v4 and v5 compatibility through separate entry points. It includes custom fields, widgets, and themes that enable developers to create JSON schema-based forms with Material Design components and styling.
3

4
## Package Information
5

6
- **Package Name**: @rjsf/material-ui
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **License**: Apache-2.0
10
- **Installation**: `npm install @rjsf/material-ui`
11

12
## Core Imports
13

14
The package provides three entry points:
15
- Main entry (`@rjsf/material-ui`): Material UI v4 by default, exports all components
16
- v4 entry (`@rjsf/material-ui/v4`): Explicit Material UI v4 theme
17
- v5 entry (`@rjsf/material-ui/v5`): Material UI v5 theme
18

19
### Default Import (Material UI v4)
20

21
```typescript
22
import Form from "@rjsf/material-ui";
23
```
24

25
### Version-Specific Imports
26

27
Material UI v4:
28
```typescript
29
import Form from "@rjsf/material-ui/v4";
30
// or
31
import { withTheme } from "@rjsf/core";
32
import Theme from "@rjsf/material-ui/v4";
33
const Form = withTheme(Theme);
34
```
35

36
Material UI v5:
37
```typescript
38
import Form from "@rjsf/material-ui/v5";
39
// or
40
import { withTheme } from "@rjsf/core";
41
import Theme from "@rjsf/material-ui/v5";
42
const Form = withTheme(Theme);
43
```
44

45
### Component Imports
46

47
```typescript
48
import { 
49
  Fields, 
50
  Widgets, 
51
  FieldTemplate, 
52
  ArrayFieldTemplate, 
53
  ObjectFieldTemplate,
54
  Theme,
55
  Theme4,
56
  Theme5,
57
  MuiForm,
58
  MuiForm4, 
59
  MuiForm5,
60
  MuiComponentContext
61
} from "@rjsf/material-ui";
62
```
63

64
CommonJS:
65
```javascript
66
const Form = require("@rjsf/material-ui").default;
67
// or
68
const { Fields, Widgets, Theme, Theme4, Theme5, MuiComponentContext } = require("@rjsf/material-ui");
69
// Version-specific
70
const Form4 = require("@rjsf/material-ui/v4").default;
71
const Form5 = require("@rjsf/material-ui/v5").default;
72
```
73

74
## Basic Usage
75

76
### Simple Form with Material UI v5
77

78
```typescript
79
import Form from "@rjsf/material-ui/v5";
80

81
const schema = {
82
  type: "object",
83
  properties: {
84
    name: { type: "string", title: "Name" },
85
    email: { type: "string", format: "email", title: "Email" },
86
    age: { type: "integer", title: "Age", minimum: 18 }
87
  },
88
  required: ["name", "email"]
89
};
90

91
function MyForm() {
92
  return (
93
    <Form
94
      schema={schema}
95
      onSubmit={({formData}) => console.log("Submitted:", formData)}
96
    />
97
  );
98
}
99
```
100

101
### Custom Theme Configuration
102

103
```typescript
104
import { withTheme } from "@rjsf/core";
105
import { Theme, Widgets } from "@rjsf/material-ui/v5";
106

107
// Customize the theme with additional widgets
108
const customTheme = {
109
  ...Theme,
110
  widgets: {
111
    ...Theme.widgets,
112
    CustomWidget: MyCustomWidget
113
  }
114
};
115

116
const CustomForm = withTheme(customTheme);
117
```
118

119
## Architecture
120

121
@rjsf/material-ui is built around several key components:
122

123
- **Dual Version Support**: Separate builds for Material UI v4 and v5 with shared component logic
124
- **Context System**: React Context provides Material UI components to widgets and fields
125
- **Theme Integration**: Extends @rjsf/core theming system with Material UI-specific implementations
126
- **Widget Library**: Comprehensive set of form controls using Material UI components
127
- **Template System**: Custom field and array templates with Material Design styling
128
- **Type Safety**: Full TypeScript support with proper type definitions for all components
129

130
## Capabilities
131

132
### Form Components
133

134
Pre-configured form components with Material UI themes and all necessary widgets and fields.
135

136
```typescript { .api }
137
declare const MuiForm: React.ComponentType<FormProps<any>>;
138
declare const MuiForm4: React.ComponentType<FormProps<any>>;
139
declare const MuiForm5: React.ComponentType<FormProps<any>>;
140
```
141

142
[Form Components](./form-components.md)
143

144
### Widgets
145

146
Complete set of form input widgets styled with Material UI components for different data types and input methods.
147

148
```typescript { .api }
149
interface WidgetCollection {
150
  CheckboxWidget: React.ComponentType<WidgetProps>;
151
  CheckboxesWidget: React.ComponentType<WidgetProps>;
152
  ColorWidget: React.ComponentType<WidgetProps>;
153
  DateWidget: React.ComponentType<WidgetProps>;
154
  DateTimeWidget: React.ComponentType<WidgetProps>;
155
  EmailWidget: React.ComponentType<WidgetProps>;
156
  PasswordWidget: React.ComponentType<WidgetProps>;
157
  RadioWidget: React.ComponentType<WidgetProps>;
158
  RangeWidget: React.ComponentType<WidgetProps>;
159
  SelectWidget: React.ComponentType<WidgetProps>;
160
  SubmitButton: React.ComponentType<WidgetProps>;
161
  TextWidget: React.ComponentType<WidgetProps>;
162
  TextareaWidget: React.ComponentType<WidgetProps>;
163
  URLWidget: React.ComponentType<WidgetProps>;
164
  UpDownWidget: React.ComponentType<WidgetProps>;
165
}
166
```
167

168
[Widgets](./widgets.md)
169

170
### Field Templates
171

172
Templates that control the layout and structure of form fields, providing consistent Material UI styling and behavior.
173

174
```typescript { .api }
175
declare const FieldTemplate: React.ComponentType<FieldTemplateProps>;
176
declare const ArrayFieldTemplate: React.ComponentType<ArrayFieldTemplateProps>;
177
declare const ObjectFieldTemplate: React.ComponentType<ObjectFieldTemplateProps>;
178
```
179

180
[Field Templates](./field-templates.md)
181

182
### Fields
183

184
Custom field components for specific rendering needs like titles and descriptions.
185

186
```typescript { .api }
187
interface FieldCollection {
188
  DescriptionField: React.ComponentType<FieldProps>;
189
  TitleField: React.ComponentType<FieldProps>;
190
}
191
```
192

193
[Fields](./fields.md)
194

195
### Themes
196

197
Theme objects that configure the complete form appearance and behavior for different Material UI versions.
198

199
```typescript { .api }
200
interface ThemeProps {
201
  _internalFormWrapper?: React.ComponentType<any>;
202
  ArrayFieldTemplate?: React.ComponentType<ArrayFieldTemplateProps>;
203
  FieldTemplate?: React.ComponentType<FieldTemplateProps>;
204
  ObjectFieldTemplate?: React.ComponentType<ObjectFieldTemplateProps>;
205
  fields?: { [key: string]: React.ComponentType<FieldProps> };
206
  widgets?: { [key: string]: React.ComponentType<WidgetProps> };
207
  ErrorList?: React.ComponentType<ErrorListProps>;
208
}
209

210
declare const Theme: ThemeProps;
211
declare const Theme4: ThemeProps;
212
declare const Theme5: ThemeProps;
213
```
214

215
[Themes](./themes.md)
216

217
### Component Context
218

219
React Context system for providing Material UI components to form elements, enabling version compatibility.
220

221
```typescript { .api }
222
declare const MuiComponentContext: React.Context<MaterialUIContextProps | Mui5ContextProps | null>;
223

224
function useMuiComponent(): MaterialUIContextProps | Mui5ContextProps;
225
```
226

227
[Component Context](./component-context.md)
228

229
### Error List
230

231
Material UI styled error list component for displaying form validation errors in a structured format.
232

233
```typescript { .api }
234
declare const ErrorList: React.ComponentType<ErrorListProps>;
235

236
interface ErrorListProps {
237
  errors: AjvError[];
238
  errorSchema: ErrorSchema;
239
  schema: JSONSchema7;
240
  uiSchema: UiSchema;
241
  formContext: any;
242
}
243
```
244

245
## Types
246

247
### Core Types
248

249
```typescript { .api }
250
// Re-exported from @rjsf/core
251
interface FormProps<T = any> {
252
  schema: JSONSchema7;
253
  formData?: T;
254
  onSubmit?: (data: ISubmitEvent<T>) => void;
255
  onChange?: (data: IChangeEvent<T>) => void;
256
  onError?: (errors: AjvError[]) => void;
257
  // ... additional FormProps from @rjsf/core
258
}
259

260
interface WidgetProps {
261
  id: string;
262
  value: any;
263
  label?: string;
264
  onChange: (value: any) => void;
265
  onBlur?: (id: string, value: any) => void;
266
  onFocus?: (id: string, value: any) => void;
267
  options?: { [key: string]: any };
268
  schema: JSONSchema7;
269
  uiSchema?: UiSchema;
270
  readonly?: boolean;
271
  disabled?: boolean;
272
  required?: boolean;
273
  multiple?: boolean;
274
  rawErrors?: string[];
275
  // ... additional properties
276
}
277

278
interface FieldProps {
279
  name: string;
280
  title?: string;
281
  description?: string;
282
  properties?: { [key: string]: any };
283
  schema: JSONSchema7;
284
  uiSchema?: UiSchema;
285
  formData?: any;
286
  // ... additional properties
287
}
288
```
289

290
### Material UI Context Types
291

292
```typescript { .api }
293
interface MaterialUIContextProps {
294
  Box: React.ComponentType<BoxProps>;
295
  Button: React.ComponentType<ButtonProps>;
296
  Checkbox: React.ComponentType<CheckboxProps>;
297
  Divider: React.ComponentType<DividerProps>;
298
  Grid: React.ComponentType<GridProps>;
299
  FormControl: React.ComponentType<FormControlProps>;
300
  FormControlLabel: React.ComponentType<FormControlLabelProps>;
301
  FormGroup: React.ComponentType<FormGroupProps>;
302
  FormHelperText: React.ComponentType<FormHelperTextProps>;
303
  FormLabel: React.ComponentType<FormLabelProps>;
304
  IconButton: React.ComponentType<IconButtonProps>;
305
  Input: React.ComponentType<InputProps>;
306
  InputLabel: React.ComponentType<InputLabelProps>;
307
  List: React.ComponentType<ListProps>;
308
  ListItem: React.ComponentType<ListItemProps>;
309
  ListItemIcon: React.ComponentType<ListItemIconProps>;
310
  ListItemText: React.ComponentType<ListItemTextProps>;
311
  MenuItem: React.ComponentType<MenuItemProps>;
312
  Paper: React.ComponentType<PaperProps>;
313
  Radio: React.ComponentType<RadioProps>;
314
  RadioGroup: React.ComponentType<RadioGroupProps>;
315
  Slider: React.ComponentType<SliderProps>;
316
  TextField: React.ComponentType<Omit<TextFieldProps, 'color' | 'variant'>>;
317
  Typography: React.ComponentType<TypographyProps>;
318
  AddIcon: React.ComponentType<SvgIconProps>;
319
  ArrowDownwardIcon: React.ComponentType<SvgIconProps>;
320
  ArrowUpwardIcon: React.ComponentType<SvgIconProps>;
321
  ErrorIcon: React.ComponentType<SvgIconProps>;
322
  RemoveIcon: React.ComponentType<SvgIconProps>;
323
}
324

325
interface Mui5ContextProps {
326
  // Same interface as MaterialUIContextProps but for @mui/material v5
327
  Box: React.ComponentType<BoxProps>;
328
  Button: React.ComponentType<ButtonProps>;
329
  // ... (same properties as MaterialUIContextProps)
330
  Input: React.ComponentType<OutlinedInputProps>; // v5 uses OutlinedInputProps instead of InputProps
331
  // ... rest of properties
332
}
333
```