0
# Theme System
1

2
Material UI theme integration with customizable themes and responsive design utilities for react-admin applications.
3

4
## Capabilities
5

6
### Predefined Themes
7

8
Ready-to-use theme configurations with different styling approaches.
9

10
```typescript { .api }
11
/**
12
 * Default Material UI theme with react-admin customizations
13
 */
14
const defaultTheme: Theme;
15

16
/**
17
 * Nano dark theme variant with dark color scheme
18
 */
19
const nanoDarkTheme: Theme;
20

21
/**
22
 * Nano light theme variant with light color scheme
23
 */
24
const nanoLightTheme: Theme;
25

26
/**
27
 * Radiant dark theme variant with enhanced dark styling
28
 */
29
const radiantDarkTheme: Theme;
30

31
/**
32
 * Radiant light theme variant with enhanced light styling
33
 */
34
const radiantLightTheme: Theme;
35
```
36

37
**Usage Examples:**
38

39
```typescript
40
import { AdminUI, defaultTheme, nanoDarkTheme } from "ra-ui-materialui";
41

42
// Using default theme
43
const App = () => (
44
  <AdminUI theme={defaultTheme}>
45
    {/* Admin content */}
46
  </AdminUI>
47
);
48

49
// Using dark theme
50
const DarkApp = () => (
51
  <AdminUI theme={nanoDarkTheme}>
52
    {/* Admin content */}
53
  </AdminUI>
54
);
55
```
56

57
### Theme Creation and Customization
58

59
Functions and components for creating and customizing themes.
60

61
```typescript { .api }
62
/**
63
 * Create custom theme configuration with Material UI options
64
 * @param options - Theme customization options
65
 * @returns Customized Material UI theme
66
 */
67
function createTheme(options?: ThemeOptions): Theme;
68

69
/**
70
 * Theme provider component for applying theme to component tree
71
 * @param props - ThemeProvider configuration props
72
 * @returns Theme context provider component
73
 */
74
function ThemeProvider(props: ThemeProviderProps): ReactElement;
75

76
interface ThemeOptions {
77
  /** Palette color configuration */
78
  palette?: PaletteOptions;
79
  /** Typography configuration */
80
  typography?: TypographyOptions;
81
  /** Spacing configuration */
82
  spacing?: SpacingOptions;
83
  /** Breakpoint configuration */
84
  breakpoints?: BreakpointsOptions;
85
  /** Component style overrides */
86
  components?: ComponentsOverrides;
87
  /** Custom CSS variables */
88
  vars?: Record<string, any>;
89
}
90

91
interface ThemeProviderProps {
92
  /** Material UI theme object */
93
  theme: Theme;
94
  /** Child components */
95
  children: ReactNode;
96
}
97
```
98

99
**Usage Examples:**
100

101
```typescript
102
import { createTheme, ThemeProvider } from "ra-ui-materialui";
103

104
// Custom theme creation
105
const customTheme = createTheme({
106
  palette: {
107
    primary: {
108
      main: '#1976d2',
109
    },
110
    secondary: {
111
      main: '#dc004e',
112
    },
113
    mode: 'light',
114
  },
115
  typography: {
116
    h1: {
117
      fontSize: '2rem',
118
    },
119
  },
120
  spacing: 8,
121
});
122

123
// Using custom theme
124
const CustomApp = () => (
125
  <ThemeProvider theme={customTheme}>
126
    <AdminUI>
127
      {/* Admin content */}
128
    </AdminUI>
129
  </ThemeProvider>
130
);
131
```
132

133
### Theme Hooks and Utilities
134

135
Hooks for accessing and manipulating theme within components.
136

137
```typescript { .api }
138
/**
139
 * Hook for accessing current theme configuration
140
 * @returns Current Material UI theme object
141
 */
142
function useTheme(): Theme;
143

144
/**
145
 * Hook for responsive media queries based on theme breakpoints
146
 * @param query - Media query string or breakpoint
147
 * @param options - Query options
148
 * @returns Boolean indicating if query matches
149
 */
150
function useMediaQuery(
151
  query: string | ((theme: Theme) => string), 
152
  options?: UseMediaQueryOptions
153
): boolean;
154

155
interface UseMediaQueryOptions {
156
  /** Default matches value during SSR */
157
  defaultMatches?: boolean;
158
  /** Match media implementation */
159
  matchMedia?: (query: string) => MediaQueryList;
160
  /** Disable hydration mismatch warning */
161
  noSsr?: boolean;
162
  /** Server-side rendering matches value */
163
  ssrMatchMedia?: (query: string) => { matches: boolean };
164
}
165
```
166

167
**Usage Examples:**
168

169
```typescript
170
import { useTheme, useMediaQuery } from "ra-ui-materialui";
171

172
const ResponsiveComponent = () => {
173
  const theme = useTheme();
174
  const isMobile = useMediaQuery(theme.breakpoints.down('sm'));
175
  const isDarkMode = theme.palette.mode === 'dark';
176
  
177
  return (
178
    <div>
179
      <p>Theme mode: {isDarkMode ? 'Dark' : 'Light'}</p>
180
      <p>Device: {isMobile ? 'Mobile' : 'Desktop'}</p>
181
      <p>Primary color: {theme.palette.primary.main}</p>
182
    </div>
183
  );
184
};
185
```
186

187
### Theme Customization Areas
188

189
Detailed configuration options for different theme aspects.
190

191
```typescript { .api }
192
interface PaletteOptions {
193
  /** Color mode */
194
  mode?: 'light' | 'dark';
195
  /** Primary color configuration */
196
  primary?: PaletteColorOptions;
197
  /** Secondary color configuration */
198
  secondary?: PaletteColorOptions;
199
  /** Error color configuration */
200
  error?: PaletteColorOptions;
201
  /** Warning color configuration */
202
  warning?: PaletteColorOptions;
203
  /** Info color configuration */
204
  info?: PaletteColorOptions;
205
  /** Success color configuration */
206
  success?: PaletteColorOptions;
207
  /** Background colors */
208
  background?: {
209
    default?: string;
210
    paper?: string;
211
  };
212
  /** Text colors */
213
  text?: {
214
    primary?: string;
215
    secondary?: string;
216
    disabled?: string;
217
  };
218
}
219

220
interface PaletteColorOptions {
221
  /** Main color */
222
  main: string;
223
  /** Light variant */
224
  light?: string;
225
  /** Dark variant */
226
  dark?: string;
227
  /** Contrast text color */
228
  contrastText?: string;
229
}
230

231
interface TypographyOptions {
232
  /** Font family */
233
  fontFamily?: string;
234
  /** Font size */
235
  fontSize?: number;
236
  /** Font weight */
237
  fontWeightLight?: number;
238
  fontWeightRegular?: number;
239
  fontWeightMedium?: number;
240
  fontWeightBold?: number;
241
  /** Typography variants */
242
  h1?: TypographyStyle;
243
  h2?: TypographyStyle;
244
  h3?: TypographyStyle;
245
  h4?: TypographyStyle;
246
  h5?: TypographyStyle;
247
  h6?: TypographyStyle;
248
  subtitle1?: TypographyStyle;
249
  subtitle2?: TypographyStyle;
250
  body1?: TypographyStyle;
251
  body2?: TypographyStyle;
252
  button?: TypographyStyle;
253
  caption?: TypographyStyle;
254
  overline?: TypographyStyle;
255
}
256

257
interface BreakpointsOptions {
258
  /** Breakpoint values */
259
  values?: {
260
    xs?: number;
261
    sm?: number;
262
    md?: number;
263
    lg?: number;
264
    xl?: number;
265
  };
266
  /** Breakpoint unit */
267
  unit?: string;
268
  /** Step value */
269
  step?: number;
270
}
271
```
272

273
### Component Style Overrides
274

275
Theme-level component customization options.
276

277
```typescript { .api }
278
interface ComponentsOverrides {
279
  /** AppBar component styles */
280
  MuiAppBar?: {
281
    styleOverrides?: {
282
      root?: CSSProperties;
283
      colorPrimary?: CSSProperties;
284
    };
285
  };
286
  /** Button component styles */
287
  MuiButton?: {
288
    styleOverrides?: {
289
      root?: CSSProperties;
290
      contained?: CSSProperties;
291
      outlined?: CSSProperties;
292
    };
293
  };
294
  /** TextField component styles */
295
  MuiTextField?: {
296
    styleOverrides?: {
297
      root?: CSSProperties;
298
    };
299
  };
300
  /** DataGrid component styles */
301
  MuiDataGrid?: {
302
    styleOverrides?: {
303
      root?: CSSProperties;
304
      columnHeaders?: CSSProperties;
305
      row?: CSSProperties;
306
    };
307
  };
308
  /** Paper component styles */
309
  MuiPaper?: {
310
    styleOverrides?: {
311
      root?: CSSProperties;
312
      elevation1?: CSSProperties;
313
    };
314
  };
315
}
316
```
317

318
**Advanced Theme Example:**
319

320
```typescript
321
import { createTheme } from "ra-ui-materialui";
322

323
const advancedTheme = createTheme({
324
  palette: {
325
    mode: 'dark',
326
    primary: {
327
      main: '#3f51b5',
328
      light: '#757de8',
329
      dark: '#002984',
330
    },
331
    secondary: {
332
      main: '#f50057',
333
      light: '#ff5983',
334
      dark: '#bb002f',
335
    },
336
    background: {
337
      default: '#121212',
338
      paper: '#1e1e1e',
339
    },
340
  },
341
  typography: {
342
    fontFamily: 'Roboto, Arial, sans-serif',
343
    h1: {
344
      fontSize: '2.5rem',
345
      fontWeight: 300,
346
    },
347
    button: {
348
      textTransform: 'none',
349
    },
350
  },
351
  components: {
352
    MuiButton: {
353
      styleOverrides: {
354
        root: {
355
          borderRadius: 8,
356
        },
357
      },
358
    },
359
    MuiAppBar: {
360
      styleOverrides: {
361
        root: {
362
          backgroundColor: '#1e1e1e',
363
        },
364
      },
365
    },
366
  },
367
  spacing: 8,
368
  breakpoints: {
369
    values: {
370
      xs: 0,
371
      sm: 600,
372
      md: 960,
373
      lg: 1280,
374
      xl: 1920,
375
    },
376
  },
377
});
378
```
379

380
## Types
381

382
```typescript { .api }
383
interface Theme {
384
  palette: Palette;
385
  typography: Typography;
386
  spacing: Spacing;
387
  breakpoints: Breakpoints;
388
  zIndex: ZIndex;
389
  transitions: Transitions;
390
  components?: ComponentsOverrides;
391
  shadows: Shadows;
392
  shape: Shape;
393
}
394

395
interface Spacing {
396
  (): number;
397
  (value: number): number;
398
  (topBottom: number, leftRight: number): number;
399
  (top: number, leftRight: number, bottom: number): number;
400
  (top: number, right: number, bottom: number, left: number): number;
401
}
402

403
interface TypographyStyle {
404
  fontFamily?: string;
405
  fontSize?: string | number;
406
  fontWeight?: string | number;
407
  lineHeight?: string | number;
408
  letterSpacing?: string | number;
409
  color?: string;
410
}
411

412
type CSSProperties = React.CSSProperties;
413
```