0
# Themes
1

2
Theme objects that configure the complete form appearance and behavior for different Material UI versions. Themes integrate with @rjsf/core's theming system to provide Material UI-specific implementations.
3

4
## Capabilities
5

6
### Theme (Material UI v4)
7

8
The default theme for Material UI v4 with Mui4FormWrapper and complete component integration.
9

10
```typescript { .api }
11
/**
12
 * Material UI v4 theme configuration with Mui4FormWrapper and ThemeCommon
13
 * Integrates with @material-ui/core components and icons
14
 */
15
declare const Theme: ThemeProps;
16
```
17

18
**Features:**
19
- Mui4FormWrapper for @material-ui/core v4 component context
20
- Complete widget and field collection
21
- Error handling with Material UI v4 components
22
- Theme-consistent styling and behavior
23

24
**Usage:**
25
```typescript
26
import { withTheme } from "@rjsf/core";
27
import Theme from "@rjsf/material-ui/v4";
28

29
const Form = withTheme(Theme);
30
```
31

32
### Theme4
33

34
Explicit alias for Material UI v4 theme (same as Theme).
35

36
```typescript { .api }
37
/**
38
 * Explicit Material UI v4 theme (alias for Theme)
39
 */
40
declare const Theme4: ThemeProps;
41
```
42

43
### Theme5
44

45
Theme for Material UI v5 with Mui5FormWrapper and @mui/material integration.
46

47
```typescript { .api }
48
/**
49
 * Material UI v5 theme configuration with Mui5FormWrapper and ThemeCommon
50
 * Integrates with @mui/material components and icons
51
 */
52
declare const Theme5: ThemeProps;
53
```
54

55
**Features:**
56
- Mui5FormWrapper for @mui/material v5 component context
57
- Complete widget and field collection
58
- Error handling with Material UI v5 components
59
- Modern Material Design 3 styling
60

61
**Usage:**
62
```typescript
63
import { withTheme } from "@rjsf/core";
64
import Theme from "@rjsf/material-ui/v5";
65

66
const Form = withTheme(Theme);
67
```
68

69
## Theme Structure
70

71
All themes implement the ThemeProps interface from @rjsf/core:
72

73
```typescript { .api }
74
interface ThemeProps {
75
  /** Internal form wrapper component for context provision */
76
  _internalFormWrapper?: React.ComponentType<any>;
77
  /** Template for array fields */
78
  ArrayFieldTemplate?: React.ComponentType<ArrayFieldTemplateProps>;
79
  /** Template for individual fields */
80
  FieldTemplate?: React.ComponentType<FieldTemplateProps>;
81
  /** Template for object fields */
82
  ObjectFieldTemplate?: React.ComponentType<ObjectFieldTemplateProps>;
83
  /** Collection of custom field components */
84
  fields?: { [key: string]: React.ComponentType<FieldProps> };
85
  /** Collection of custom widget components */
86
  widgets?: { [key: string]: React.ComponentType<WidgetProps> };
87
  /** Error list component */
88
  ErrorList?: React.ComponentType<ErrorListProps>;
89
}
90
```
91

92
## Theme Components
93

94
### ThemeCommon
95

96
Shared theme configuration used by both v4 and v5 themes:
97

98
```typescript { .api }
99
interface ThemeCommonConfig {
100
  /** Array field template with Material UI styling */
101
  ArrayFieldTemplate: React.ComponentType<ArrayFieldTemplateProps>;
102
  /** Combined fields from default registry and custom fields */
103
  fields: { [key: string]: React.ComponentType<FieldProps> };
104
  /** Individual field template */
105
  FieldTemplate: React.ComponentType<FieldTemplateProps>;
106
  /** Object field template */
107
  ObjectFieldTemplate: React.ComponentType<ObjectFieldTemplateProps>;
108
  /** Combined widgets from default registry and custom widgets */
109
  widgets: { [key: string]: React.ComponentType<WidgetProps> };
110
  /** Error list component */
111
  ErrorList: React.ComponentType<ErrorListProps>;
112
}
113
```
114

115
### Form Wrappers
116

117
#### Mui4FormWrapper
118

119
Form wrapper that provides Material UI v4 context to all child components:
120

121
```typescript { .api }
122
/**
123
 * Form wrapper that provides @material-ui/core v4 components via MuiComponentContext
124
 * Shows warning if Material UI v4 dependencies are not available
125
 */
126
declare const Mui4FormWrapper: React.ForwardRefExoticComponent<
127
  React.PropsWithChildren<HTMLFormElement> & React.RefAttributes<HTMLBaseElement>
128
>;
129
```
130

131
#### Mui5FormWrapper
132

133
Form wrapper that provides Material UI v5 context to all child components:
134

135
```typescript { .api }
136
/**
137
 * Form wrapper that provides @mui/material v5 components via MuiComponentContext
138
 * Shows warning if Material UI v5 dependencies are not available
139
 */
140
declare const Mui5FormWrapper: React.ForwardRefExoticComponent<
141
  React.PropsWithChildren<HTMLFormElement> & React.RefAttributes<HTMLBaseElement>
142
>;
143
```
144

145
## Theme Customization
146

147
### Basic Theme Extension
148

149
```typescript
150
import { withTheme } from "@rjsf/core";
151
import { Theme } from "@rjsf/material-ui/v5";
152

153
const customTheme = {
154
  ...Theme,
155
  widgets: {
156
    ...Theme.widgets,
157
    CustomWidget: MyCustomWidget,
158
  },
159
  fields: {
160
    ...Theme.fields,
161
    CustomField: MyCustomField,
162
  },
163
};
164

165
const CustomForm = withTheme(customTheme);
166
```
167

168
### Advanced Theme Customization
169

170
```typescript
171
import { ThemeProps } from "@rjsf/core";
172
import { Theme5 } from "@rjsf/material-ui";
173

174
const advancedTheme: ThemeProps = {
175
  ...Theme5,
176
  FieldTemplate: CustomFieldTemplate,
177
  ArrayFieldTemplate: CustomArrayTemplate,
178
  ErrorList: CustomErrorList,
179
  widgets: {
180
    ...Theme5.widgets,
181
    TextWidget: EnhancedTextWidget,
182
    SelectWidget: EnhancedSelectWidget,
183
  },
184
};
185

186
const AdvancedForm = withTheme(advancedTheme);
187
```
188

189
### Conditional Theme Selection
190

191
```typescript
192
import { Theme as Theme4, Theme5 } from "@rjsf/material-ui";
193

194
function useThemeForVersion(version: 4 | 5) {
195
  return version === 5 ? Theme5 : Theme4;
196
}
197

198
function AdaptiveForm({ materialUIVersion = 5 }) {
199
  const theme = useThemeForVersion(materialUIVersion);
200
  const Form = withTheme(theme);
201
  
202
  return <Form schema={schema} />;
203
}
204
```
205

206
## Error Handling
207

208
All themes include error handling components:
209

210
### ErrorList Component
211

212
Displays form validation errors using Material UI components:
213

214
```typescript { .api }
215
/**
216
 * Error display component using Paper, List, and ErrorIcon
217
 * @param props - ErrorListProps containing validation errors
218
 * @returns JSX.Element
219
 */
220
declare const ErrorList: React.ComponentType<ErrorListProps>;
221

222
interface ErrorListProps {
223
  /** List of validation errors */
224
  errors?: RJSFValidationError[];
225
  /** Error schema object */
226
  errorSchema?: ErrorSchema;
227
  /** Schema being validated */
228
  schema?: JSONSchema7;
229
  /** UI schema */
230
  uiSchema?: UiSchema;
231
  /** Form context */
232
  formContext?: any;
233
}
234
```
235

236
## Integration Examples
237

238
### With Material UI ThemeProvider
239

240
```typescript
241
import { createTheme, ThemeProvider } from "@mui/material/styles";
242
import Form from "@rjsf/material-ui/v5";
243

244
const muiTheme = createTheme({
245
  palette: {
246
    primary: {
247
      main: '#1976d2',
248
    },
249
    secondary: {
250
      main: '#dc004e',
251
    },
252
  },
253
});
254

255
function ThemedForm() {
256
  return (
257
    <ThemeProvider theme={muiTheme}>
258
      <Form schema={schema} />
259
    </ThemeProvider>
260
  );
261
}
262
```
263

264
### Multiple Forms with Different Themes
265

266
```typescript
267
import { Theme as Theme4, Theme5 } from "@rjsf/material-ui";
268
import { withTheme } from "@rjsf/core";
269

270
const Form4 = withTheme(Theme4);
271
const Form5 = withTheme(Theme5);
272

273
function MultiVersionForms() {
274
  return (
275
    <>
276
      <h2>Material UI v4 Form</h2>
277
      <Form4 schema={schema4} />
278
      
279
      <h2>Material UI v5 Form</h2>
280
      <Form5 schema={schema5} />
281
    </>
282
  );
283
}
284
```
285

286
### Custom Theme with Feature Flags
287

288
```typescript
289
import { Theme5 } from "@rjsf/material-ui";
290

291
function createFeatureTheme(features: FeatureFlags): ThemeProps {
292
  const theme = { ...Theme5 };
293
  
294
  if (features.enhancedValidation) {
295
    theme.ErrorList = EnhancedErrorList;
296
  }
297
  
298
  if (features.advancedWidgets) {
299
    theme.widgets = {
300
      ...theme.widgets,
301
      DateTimeWidget: AdvancedDateTimeWidget,
302
    };
303
  }
304
  
305
  return theme;
306
}
307

308
const FeatureForm = withTheme(createFeatureTheme({
309
  enhancedValidation: true,
310
  advancedWidgets: false,
311
}));
312
```
313

314
## Version Compatibility
315

316
- **Theme/Theme4**: Compatible with @material-ui/core v4.12.3+
317
- **Theme5**: Compatible with @mui/material v5.2.2+
318
- **Context Detection**: Themes automatically detect available Material UI version
319
- **Graceful Degradation**: Shows warning messages if required dependencies are missing
320
- **Peer Dependencies**: All Material UI dependencies are optional to support dual installation