diff --git a/docs/data/material/customization/shape/shape.md b/docs/data/material/customization/shape/shape.md
new file mode 100644
index 00000000000000..ba3468f1705226
--- /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 custom shapes, 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 ;
+}
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",
diff --git a/packages/mui-material/src/styles/createThemeFoundation.ts b/packages/mui-material/src/styles/createThemeFoundation.ts
index 6c8df594dd976a..eaca3a4ff938f8 100644
--- a/packages/mui-material/src/styles/createThemeFoundation.ts
+++ b/packages/mui-material/src/styles/createThemeFoundation.ts
@@ -1,5 +1,13 @@
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,
+ ShapeOptions as SystemShapeOptions,
+} from '@mui/system';
import { ExtractTypographyTokens } from '@mui/system/cssVars';
import { Palette, PaletteOptions } from './createPalette';
import { Shadows } from './shadows';
@@ -205,6 +213,10 @@ export interface PaletteTooltip {
bg: string;
}
+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 & {
@@ -290,7 +302,7 @@ export interface ThemeVars {
opacity: Opacity;
overlays: Overlays;
shadows: Shadows;
- shape: SystemTheme['shape'];
+ shape: Shape;
spacing: string;
zIndex: ZIndex;
}
@@ -397,7 +409,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..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 } 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;
@@ -49,6 +56,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..4d2eba3c5116f3 100644
--- a/packages/mui-material/src/styles/createThemeWithVars.d.ts
+++ b/packages/mui-material/src/styles/createThemeWithVars.d.ts
@@ -35,6 +35,8 @@ import {
ThemeCssVarOverrides,
ThemeCssVar,
CssVarsTheme,
+ Shape,
+ ShapeOptions,
} from './createThemeFoundation';
// Re-export all types from foundation to maintain backward compatibility
@@ -73,6 +75,8 @@ export type {
ThemeCssVarOverrides,
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 990e9e97ebaba2..3dc722e2fea780 100644
--- a/packages/mui-material/src/styles/index.d.ts
+++ b/packages/mui-material/src/styles/index.d.ts
@@ -158,6 +158,8 @@ export type {
ThemeCssVar,
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
new file mode 100644
index 00000000000000..8310780411b139
--- /dev/null
+++ b/packages/mui-material/test/typescript/moduleAugmentation/shape.spec.ts
@@ -0,0 +1,29 @@
+import { createTheme } from '@mui/material/styles';
+
+declare module '@mui/material/styles' {
+ interface Shape {
+ borderRadiusSecondary: number;
+ }
+
+ interface ShapeOptions {
+ borderRadiusSecondary: number;
+ }
+}
+
+createTheme({
+ shape: {
+ borderRadiusSecondary: 12,
+ },
+ 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"]
+}