From 893c1a04dea03ac91b8e55d418bef515624fc4db Mon Sep 17 00:00:00 2001 From: siriwatknp Date: Mon, 3 Nov 2025 11:14:36 +0700 Subject: [PATCH 1/6] fix shape type augmentation --- .../src/styles/createThemeFoundation.ts | 15 ++++++++++++--- .../src/styles/createThemeNoVars.d.ts | 3 ++- .../src/styles/createThemeWithVars.d.ts | 2 ++ packages/mui-material/src/styles/index.d.ts | 1 + 4 files changed, 17 insertions(+), 4 deletions(-) diff --git a/packages/mui-material/src/styles/createThemeFoundation.ts b/packages/mui-material/src/styles/createThemeFoundation.ts index 6c8df594dd976a..00fb293e638c45 100644 --- a/packages/mui-material/src/styles/createThemeFoundation.ts +++ b/packages/mui-material/src/styles/createThemeFoundation.ts @@ -1,5 +1,12 @@ import { OverridableStringUnion } from '@mui/types'; -import { SxConfig, SxProps, CSSObject, ApplyStyles, Theme as SystemTheme } from '@mui/system'; +import { + SxConfig, + SxProps, + CSSObject, + ApplyStyles, + Theme as SystemTheme, + Shape as SystemShape, +} from '@mui/system'; import { ExtractTypographyTokens } from '@mui/system/cssVars'; import { Palette, PaletteOptions } from './createPalette'; import { Shadows } from './shadows'; @@ -205,6 +212,8 @@ export interface PaletteTooltip { bg: string; } +export interface Shape extends SystemShape {} + // The Palette should be sync with `../themeCssVarsAugmentation/index.d.ts` export interface ColorSystemOptions { palette?: PaletteOptions & { @@ -290,7 +299,7 @@ export interface ThemeVars { opacity: Opacity; overlays: Overlays; shadows: Shadows; - shape: SystemTheme['shape']; + shape: Shape; spacing: string; zIndex: ZIndex; } @@ -397,7 +406,7 @@ export interface CssVarsTheme extends ColorSystem { // Default theme tokens spacing: SystemTheme['spacing']; breakpoints: SystemTheme['breakpoints']; - shape: SystemTheme['shape']; + shape: Shape; typography: TypographyVariants; transitions: Transitions; shadows: Shadows; diff --git a/packages/mui-material/src/styles/createThemeNoVars.d.ts b/packages/mui-material/src/styles/createThemeNoVars.d.ts index eb05eb58966f68..00347d9c92ff3b 100644 --- a/packages/mui-material/src/styles/createThemeNoVars.d.ts +++ b/packages/mui-material/src/styles/createThemeNoVars.d.ts @@ -12,7 +12,7 @@ import { Shadows } from './shadows'; import { Transitions, TransitionsOptions } from './createTransitions'; import { ZIndex, ZIndexOptions } from './zIndex'; import { Components } from './components'; -import { CssVarsTheme, CssVarsPalette, ColorSystemOptions } from './createThemeFoundation'; +import { CssVarsTheme, CssVarsPalette, ColorSystemOptions, Shape } from './createThemeFoundation'; /** * To disable custom properties, use module augmentation @@ -49,6 +49,7 @@ export interface BaseTheme extends SystemTheme { mixins: Mixins; palette: Palette & (CssThemeVariables extends { enabled: true } ? CssVarsPalette : {}); shadows: Shadows; + shape: Shape; transitions: Transitions; typography: TypographyVariants; zIndex: ZIndex; diff --git a/packages/mui-material/src/styles/createThemeWithVars.d.ts b/packages/mui-material/src/styles/createThemeWithVars.d.ts index 16f1891bae49aa..fb5a34558084ca 100644 --- a/packages/mui-material/src/styles/createThemeWithVars.d.ts +++ b/packages/mui-material/src/styles/createThemeWithVars.d.ts @@ -35,6 +35,7 @@ import { ThemeCssVarOverrides, ThemeCssVar, CssVarsTheme, + Shape, } from './createThemeFoundation'; // Re-export all types from foundation to maintain backward compatibility @@ -73,6 +74,7 @@ export type { ThemeCssVarOverrides, ThemeCssVar, CssVarsTheme, + Shape, }; export interface CssVarsThemeOptions extends Omit { diff --git a/packages/mui-material/src/styles/index.d.ts b/packages/mui-material/src/styles/index.d.ts index 990e9e97ebaba2..9551d75a619157 100644 --- a/packages/mui-material/src/styles/index.d.ts +++ b/packages/mui-material/src/styles/index.d.ts @@ -158,6 +158,7 @@ export type { ThemeCssVar, ThemeCssVarOverrides, ColorSystemOptions, + Shape, } from './createThemeWithVars'; export { default as getOverlayAlpha } from './getOverlayAlpha'; export { default as shouldSkipGeneratingVar } from './shouldSkipGeneratingVar'; From 3e03cb7ce11d23ce2afcae390928785e1c74e9d3 Mon Sep 17 00:00:00 2001 From: siriwatknp Date: Mon, 3 Nov 2025 11:19:23 +0700 Subject: [PATCH 2/6] add theme augmentation test --- .../moduleAugmentation/shape.spec.ts | 23 +++++++++++++++++++ .../moduleAugmentation/shape.tsconfig.json | 4 ++++ 2 files changed, 27 insertions(+) create mode 100644 packages/mui-material/test/typescript/moduleAugmentation/shape.spec.ts create mode 100644 packages/mui-material/test/typescript/moduleAugmentation/shape.tsconfig.json diff --git a/packages/mui-material/test/typescript/moduleAugmentation/shape.spec.ts b/packages/mui-material/test/typescript/moduleAugmentation/shape.spec.ts new file mode 100644 index 00000000000000..a49e34e486a228 --- /dev/null +++ b/packages/mui-material/test/typescript/moduleAugmentation/shape.spec.ts @@ -0,0 +1,23 @@ +import { createTheme } from '@mui/material/styles'; + +declare module '@mui/material/styles' { + interface Shape { + borderRadius: number; + borderRadiusSecondary: number; // custom prop + } +} + +createTheme({ + components: { + MuiButton: { + styleOverrides: { + root: ({ theme }) => ({ + borderRadius: theme.shape.borderRadiusSecondary, + '&:hover': { + borderRadius: theme.vars.shape.borderRadiusSecondary, + }, + }), + }, + }, + }, +}); diff --git a/packages/mui-material/test/typescript/moduleAugmentation/shape.tsconfig.json b/packages/mui-material/test/typescript/moduleAugmentation/shape.tsconfig.json new file mode 100644 index 00000000000000..ddc67ab761b7c4 --- /dev/null +++ b/packages/mui-material/test/typescript/moduleAugmentation/shape.tsconfig.json @@ -0,0 +1,4 @@ +{ + "extends": "../../../../../tsconfig.json", + "files": ["shape.spec.ts"] +} From 6147727534194d7e613f716af0ef211009026da9 Mon Sep 17 00:00:00 2001 From: siriwatknp Date: Mon, 3 Nov 2025 11:44:15 +0700 Subject: [PATCH 3/6] export ShapeOptions --- .../mui-material/src/styles/createThemeFoundation.ts | 3 +++ .../mui-material/src/styles/createThemeNoVars.d.ts | 9 ++++++++- .../mui-material/src/styles/createThemeWithVars.d.ts | 2 ++ packages/mui-material/src/styles/index.d.ts | 1 + .../test/typescript/moduleAugmentation/shape.spec.ts | 10 ++++++++-- 5 files changed, 22 insertions(+), 3 deletions(-) diff --git a/packages/mui-material/src/styles/createThemeFoundation.ts b/packages/mui-material/src/styles/createThemeFoundation.ts index 00fb293e638c45..eaca3a4ff938f8 100644 --- a/packages/mui-material/src/styles/createThemeFoundation.ts +++ b/packages/mui-material/src/styles/createThemeFoundation.ts @@ -6,6 +6,7 @@ import { ApplyStyles, Theme as SystemTheme, Shape as SystemShape, + ShapeOptions as SystemShapeOptions, } from '@mui/system'; import { ExtractTypographyTokens } from '@mui/system/cssVars'; import { Palette, PaletteOptions } from './createPalette'; @@ -214,6 +215,8 @@ export interface PaletteTooltip { export interface Shape extends SystemShape {} +export interface ShapeOptions extends SystemShapeOptions {} + // The Palette should be sync with `../themeCssVarsAugmentation/index.d.ts` export interface ColorSystemOptions { palette?: PaletteOptions & { diff --git a/packages/mui-material/src/styles/createThemeNoVars.d.ts b/packages/mui-material/src/styles/createThemeNoVars.d.ts index 00347d9c92ff3b..e7a1cf61da9225 100644 --- a/packages/mui-material/src/styles/createThemeNoVars.d.ts +++ b/packages/mui-material/src/styles/createThemeNoVars.d.ts @@ -12,7 +12,13 @@ import { Shadows } from './shadows'; import { Transitions, TransitionsOptions } from './createTransitions'; import { ZIndex, ZIndexOptions } from './zIndex'; import { Components } from './components'; -import { CssVarsTheme, CssVarsPalette, ColorSystemOptions, Shape } from './createThemeFoundation'; +import { + CssVarsTheme, + CssVarsPalette, + ColorSystemOptions, + Shape, + ShapeOptions, +} from './createThemeFoundation'; /** * To disable custom properties, use module augmentation @@ -37,6 +43,7 @@ export interface ThemeOptions extends Omit, CssVar components?: Components>; palette?: PaletteOptions; shadows?: Shadows; + shape?: ShapeOptions; transitions?: TransitionsOptions; typography?: TypographyVariantsOptions | ((palette: Palette) => TypographyVariantsOptions); zIndex?: ZIndexOptions; diff --git a/packages/mui-material/src/styles/createThemeWithVars.d.ts b/packages/mui-material/src/styles/createThemeWithVars.d.ts index fb5a34558084ca..4d2eba3c5116f3 100644 --- a/packages/mui-material/src/styles/createThemeWithVars.d.ts +++ b/packages/mui-material/src/styles/createThemeWithVars.d.ts @@ -36,6 +36,7 @@ import { ThemeCssVar, CssVarsTheme, Shape, + ShapeOptions, } from './createThemeFoundation'; // Re-export all types from foundation to maintain backward compatibility @@ -75,6 +76,7 @@ export type { ThemeCssVar, CssVarsTheme, Shape, + ShapeOptions, }; export interface CssVarsThemeOptions extends Omit { diff --git a/packages/mui-material/src/styles/index.d.ts b/packages/mui-material/src/styles/index.d.ts index 9551d75a619157..3dc722e2fea780 100644 --- a/packages/mui-material/src/styles/index.d.ts +++ b/packages/mui-material/src/styles/index.d.ts @@ -159,6 +159,7 @@ export type { ThemeCssVarOverrides, ColorSystemOptions, Shape, + ShapeOptions, } from './createThemeWithVars'; export { default as getOverlayAlpha } from './getOverlayAlpha'; export { default as shouldSkipGeneratingVar } from './shouldSkipGeneratingVar'; diff --git a/packages/mui-material/test/typescript/moduleAugmentation/shape.spec.ts b/packages/mui-material/test/typescript/moduleAugmentation/shape.spec.ts index a49e34e486a228..8310780411b139 100644 --- a/packages/mui-material/test/typescript/moduleAugmentation/shape.spec.ts +++ b/packages/mui-material/test/typescript/moduleAugmentation/shape.spec.ts @@ -2,12 +2,18 @@ import { createTheme } from '@mui/material/styles'; declare module '@mui/material/styles' { interface Shape { - borderRadius: number; - borderRadiusSecondary: number; // custom prop + borderRadiusSecondary: number; + } + + interface ShapeOptions { + borderRadiusSecondary: number; } } createTheme({ + shape: { + borderRadiusSecondary: 12, + }, components: { MuiButton: { styleOverrides: { From ffb7c827c5503ca72c3971e756e162192c240c09 Mon Sep 17 00:00:00 2001 From: siriwatknp Date: Mon, 3 Nov 2025 12:01:16 +0700 Subject: [PATCH 4/6] add new shape page --- .../material/customization/shape/shape.md | 46 +++++++++++++++++++ docs/data/material/pages.ts | 1 + docs/pages/material-ui/customization/shape.js | 6 +++ 3 files changed, 53 insertions(+) create mode 100644 docs/data/material/customization/shape/shape.md create mode 100644 docs/pages/material-ui/customization/shape.js diff --git a/docs/data/material/customization/shape/shape.md b/docs/data/material/customization/shape/shape.md new file mode 100644 index 00000000000000..bf6f40530f4d4a --- /dev/null +++ b/docs/data/material/customization/shape/shape.md @@ -0,0 +1,46 @@ +# Shape + +

The shape is a design token that helps control the border radius of components.

+ +The `shape` contains a single property, `borderRadius`, with the default value of `4px`. +Several components use this value to set consistent border radii across the library. + +## Custom shape + +To add a custom shape or the border radius, create a theme with the `shape` key: + +```js +import { createTheme } from '@mui/material/styles'; + +const theme = createTheme({ + shape: { + borderRadius: 8, + borderRadiusSm: 4, // new property + borderRadiusMd: 8, // new property + borderRadiusLg: 16, // new property + borderRadiusXl: 24, // new property + }, +}); +``` + +### Typescript + +If you're using TypeScript you need to use [module augmentation](/material-ui/guides/typescript/#customization-of-theme) to extend **new** shape properties to the theme. + +```ts +declare module '@mui/material/styles' { + interface Shape { + borderRadiusSm: number; + borderRadiusMd: number; + borderRadiusLg: number; + borderRadiusXl: number; + } + + interface ShapeOptions { + borderRadiusSm?: number; + borderRadiusMd?: number; + borderRadiusLg?: number; + borderRadiusXl?: number; + } +} +``` diff --git a/docs/data/material/pages.ts b/docs/data/material/pages.ts index c905cb5a170ecc..c18da518ffbdb2 100644 --- a/docs/data/material/pages.ts +++ b/docs/data/material/pages.ts @@ -195,6 +195,7 @@ const pages: MuiPage[] = [ { pathname: '/material-ui/customization/palette' }, { pathname: '/material-ui/customization/typography' }, { pathname: '/material-ui/customization/spacing' }, + { pathname: '/material-ui/customization/shape' }, { pathname: '/material-ui/customization/breakpoints' }, { pathname: '/material-ui/customization/container-queries', diff --git a/docs/pages/material-ui/customization/shape.js b/docs/pages/material-ui/customization/shape.js new file mode 100644 index 00000000000000..33043ddb792c44 --- /dev/null +++ b/docs/pages/material-ui/customization/shape.js @@ -0,0 +1,6 @@ +import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs'; +import * as pageProps from 'docs/data/material/customization/shape/shape.md?muiMarkdown'; + +export default function Page() { + return ; +} From 2f2d0d6300eab7f481855743b842a008ecabb68f Mon Sep 17 00:00:00 2001 From: siriwatknp Date: Mon, 3 Nov 2025 12:31:00 +0700 Subject: [PATCH 5/6] docs:i18n --- docs/translations/translations.json | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/translations/translations.json b/docs/translations/translations.json index ba9dc9fdd1e599..781cd0bb04366b 100644 --- a/docs/translations/translations.json +++ b/docs/translations/translations.json @@ -138,6 +138,7 @@ "/material-ui/customization/palette": "Palette", "/material-ui/customization/typography": "Typography", "/material-ui/customization/spacing": "Spacing", + "/material-ui/customization/shape": "Shape", "/material-ui/customization/breakpoints": "Breakpoints", "/material-ui/customization/container-queries": "Container queries", "/material-ui/customization/density": "Density", From 63cf433fd5cd2c85c69fa6f24a6dc193c07a4de5 Mon Sep 17 00:00:00 2001 From: siriwatknp Date: Mon, 3 Nov 2025 12:37:53 +0700 Subject: [PATCH 6/6] update docs --- docs/data/material/customization/shape/shape.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/data/material/customization/shape/shape.md b/docs/data/material/customization/shape/shape.md index bf6f40530f4d4a..ba3468f1705226 100644 --- a/docs/data/material/customization/shape/shape.md +++ b/docs/data/material/customization/shape/shape.md @@ -7,7 +7,7 @@ Several components use this value to set consistent border radii across the libr ## Custom shape -To add a custom shape or the border radius, create a theme with the `shape` key: +To add custom shapes, create a theme with the `shape` key: ```js import { createTheme } from '@mui/material/styles';