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"] +}