diff --git a/docs/data/material/components/buttons/ContainedButtons.js b/docs/data/material/components/buttons/ContainedButtons.js deleted file mode 100644 index f6ee5f5ed1d4fc..00000000000000 --- a/docs/data/material/components/buttons/ContainedButtons.js +++ /dev/null @@ -1,17 +0,0 @@ -import * as React from 'react'; -import Button from '@mui/material/Button'; -import Stack from '@mui/material/Stack'; - -export default function ContainedButtons() { - return ( - - - - - - ); -} diff --git a/docs/data/material/components/buttons/ContainedButtons.tsx b/docs/data/material/components/buttons/ContainedButtons.tsx deleted file mode 100644 index f6ee5f5ed1d4fc..00000000000000 --- a/docs/data/material/components/buttons/ContainedButtons.tsx +++ /dev/null @@ -1,17 +0,0 @@ -import * as React from 'react'; -import Button from '@mui/material/Button'; -import Stack from '@mui/material/Stack'; - -export default function ContainedButtons() { - return ( - - - - - - ); -} diff --git a/docs/data/material/components/buttons/ContainedButtons.tsx.preview b/docs/data/material/components/buttons/ContainedButtons.tsx.preview deleted file mode 100644 index f8903cf5ff7471..00000000000000 --- a/docs/data/material/components/buttons/ContainedButtons.tsx.preview +++ /dev/null @@ -1,7 +0,0 @@ - - - \ No newline at end of file diff --git a/docs/data/material/components/buttons/CustomizedButtons.js b/docs/data/material/components/buttons/CustomizedButtons.js deleted file mode 100644 index cf5616057f3e4e..00000000000000 --- a/docs/data/material/components/buttons/CustomizedButtons.js +++ /dev/null @@ -1,60 +0,0 @@ -import * as React from 'react'; -import { styled } from '@mui/material/styles'; -import Button from '@mui/material/Button'; -import Stack from '@mui/material/Stack'; -import { purple } from '@mui/material/colors'; - -const BootstrapButton = styled(Button)({ - boxShadow: 'none', - textTransform: 'none', - fontSize: 16, - padding: '6px 12px', - border: '1px solid', - lineHeight: 1.5, - backgroundColor: '#0063cc', - borderColor: '#0063cc', - fontFamily: [ - '-apple-system', - 'BlinkMacSystemFont', - '"Segoe UI"', - 'Roboto', - '"Helvetica Neue"', - 'Arial', - 'sans-serif', - '"Apple Color Emoji"', - '"Segoe UI Emoji"', - '"Segoe UI Symbol"', - ].join(','), - '&:hover': { - backgroundColor: '#0069d9', - borderColor: '#0062cc', - boxShadow: 'none', - }, - '&:active': { - boxShadow: 'none', - backgroundColor: '#0062cc', - borderColor: '#005cbf', - }, - '&:focus': { - boxShadow: '0 0 0 0.2rem rgba(0,123,255,.5)', - }, -}); - -const ColorButton = styled(Button)(({ theme }) => ({ - color: theme.palette.getContrastText(purple[500]), - backgroundColor: purple[500], - '&:hover': { - backgroundColor: purple[700], - }, -})); - -export default function CustomizedButtons() { - return ( - - Custom CSS - - Bootstrap - - - ); -} diff --git a/docs/data/material/components/buttons/CustomizedButtons.tsx b/docs/data/material/components/buttons/CustomizedButtons.tsx deleted file mode 100644 index 1be36f3f0ab3bb..00000000000000 --- a/docs/data/material/components/buttons/CustomizedButtons.tsx +++ /dev/null @@ -1,60 +0,0 @@ -import * as React from 'react'; -import { styled } from '@mui/material/styles'; -import Button, { ButtonProps } from '@mui/material/Button'; -import Stack from '@mui/material/Stack'; -import { purple } from '@mui/material/colors'; - -const BootstrapButton = styled(Button)({ - boxShadow: 'none', - textTransform: 'none', - fontSize: 16, - padding: '6px 12px', - border: '1px solid', - lineHeight: 1.5, - backgroundColor: '#0063cc', - borderColor: '#0063cc', - fontFamily: [ - '-apple-system', - 'BlinkMacSystemFont', - '"Segoe UI"', - 'Roboto', - '"Helvetica Neue"', - 'Arial', - 'sans-serif', - '"Apple Color Emoji"', - '"Segoe UI Emoji"', - '"Segoe UI Symbol"', - ].join(','), - '&:hover': { - backgroundColor: '#0069d9', - borderColor: '#0062cc', - boxShadow: 'none', - }, - '&:active': { - boxShadow: 'none', - backgroundColor: '#0062cc', - borderColor: '#005cbf', - }, - '&:focus': { - boxShadow: '0 0 0 0.2rem rgba(0,123,255,.5)', - }, -}); - -const ColorButton = styled(Button)(({ theme }) => ({ - color: theme.palette.getContrastText(purple[500]), - backgroundColor: purple[500], - '&:hover': { - backgroundColor: purple[700], - }, -})); - -export default function CustomizedButtons() { - return ( - - Custom CSS - - Bootstrap - - - ); -} diff --git a/docs/data/material/components/buttons/CustomizedButtons.tsx.preview b/docs/data/material/components/buttons/CustomizedButtons.tsx.preview deleted file mode 100644 index 5cf7e960f8c4eb..00000000000000 --- a/docs/data/material/components/buttons/CustomizedButtons.tsx.preview +++ /dev/null @@ -1,4 +0,0 @@ -Custom CSS - - Bootstrap - \ No newline at end of file diff --git a/docs/data/material/components/buttons/DisableElevation.js b/docs/data/material/components/buttons/DisableElevation.js index ba2f63127dab8d..d583f4b87da8d6 100644 --- a/docs/data/material/components/buttons/DisableElevation.js +++ b/docs/data/material/components/buttons/DisableElevation.js @@ -1,10 +1,14 @@ import * as React from 'react'; +import Stack from '@mui/material/Stack'; import Button from '@mui/material/Button'; export default function DisableElevation() { return ( - + + + + ); } diff --git a/docs/data/material/components/buttons/DisableElevation.tsx b/docs/data/material/components/buttons/DisableElevation.tsx index ba2f63127dab8d..d583f4b87da8d6 100644 --- a/docs/data/material/components/buttons/DisableElevation.tsx +++ b/docs/data/material/components/buttons/DisableElevation.tsx @@ -1,10 +1,14 @@ import * as React from 'react'; +import Stack from '@mui/material/Stack'; import Button from '@mui/material/Button'; export default function DisableElevation() { return ( - + + + + ); } diff --git a/docs/data/material/components/buttons/DisableElevation.tsx.preview b/docs/data/material/components/buttons/DisableElevation.tsx.preview index 4f12bf06dc4b44..5c905a7864f2d6 100644 --- a/docs/data/material/components/buttons/DisableElevation.tsx.preview +++ b/docs/data/material/components/buttons/DisableElevation.tsx.preview @@ -1,3 +1,4 @@ + \ No newline at end of file diff --git a/docs/data/material/components/buttons/DisabledButton.js b/docs/data/material/components/buttons/DisabledButton.js new file mode 100644 index 00000000000000..6fe82a580e4502 --- /dev/null +++ b/docs/data/material/components/buttons/DisabledButton.js @@ -0,0 +1,14 @@ +import * as React from 'react'; +import Stack from '@mui/material/Stack'; +import Button from '@mui/material/Button'; + +export default function DisabledButton() { + return ( + + + + + ); +} diff --git a/docs/data/material/components/buttons/DisabledButton.tsx b/docs/data/material/components/buttons/DisabledButton.tsx new file mode 100644 index 00000000000000..6fe82a580e4502 --- /dev/null +++ b/docs/data/material/components/buttons/DisabledButton.tsx @@ -0,0 +1,14 @@ +import * as React from 'react'; +import Stack from '@mui/material/Stack'; +import Button from '@mui/material/Button'; + +export default function DisabledButton() { + return ( + + + + + ); +} diff --git a/docs/data/material/components/buttons/DisabledButton.tsx.preview b/docs/data/material/components/buttons/DisabledButton.tsx.preview new file mode 100644 index 00000000000000..de72d167ccbbc3 --- /dev/null +++ b/docs/data/material/components/buttons/DisabledButton.tsx.preview @@ -0,0 +1,4 @@ + + \ No newline at end of file diff --git a/docs/data/material/components/buttons/FullWidthButton.js b/docs/data/material/components/buttons/FullWidthButton.js new file mode 100644 index 00000000000000..1f084c93fb5a97 --- /dev/null +++ b/docs/data/material/components/buttons/FullWidthButton.js @@ -0,0 +1,20 @@ +import * as React from 'react'; +import Box from '@mui/material/Box'; +import Button from '@mui/material/Button'; + +export default function FullWidthButton() { + return ( + + + + ); +} diff --git a/docs/data/material/components/buttons/FullWidthButton.tsx b/docs/data/material/components/buttons/FullWidthButton.tsx new file mode 100644 index 00000000000000..1f084c93fb5a97 --- /dev/null +++ b/docs/data/material/components/buttons/FullWidthButton.tsx @@ -0,0 +1,20 @@ +import * as React from 'react'; +import Box from '@mui/material/Box'; +import Button from '@mui/material/Button'; + +export default function FullWidthButton() { + return ( + + + + ); +} diff --git a/docs/data/material/components/buttons/FullWidthButton.tsx.preview b/docs/data/material/components/buttons/FullWidthButton.tsx.preview new file mode 100644 index 00000000000000..84ffd56ae97157 --- /dev/null +++ b/docs/data/material/components/buttons/FullWidthButton.tsx.preview @@ -0,0 +1,3 @@ + \ No newline at end of file diff --git a/docs/data/material/components/buttons/IntroButtons.js b/docs/data/material/components/buttons/IntroButtons.js new file mode 100644 index 00000000000000..82116201e56d99 --- /dev/null +++ b/docs/data/material/components/buttons/IntroButtons.js @@ -0,0 +1,32 @@ +import * as React from 'react'; +import Button from '@mui/material/Button'; +import DeleteIcon from '@mui/icons-material/Delete'; +import CheckIcon from '@mui/icons-material/Check'; +import Stack from '@mui/material/Stack'; + +export default function IntroButtons() { + return ( + + + + + + ); +} diff --git a/docs/data/material/components/buttons/IntroButtons.tsx b/docs/data/material/components/buttons/IntroButtons.tsx new file mode 100644 index 00000000000000..82116201e56d99 --- /dev/null +++ b/docs/data/material/components/buttons/IntroButtons.tsx @@ -0,0 +1,32 @@ +import * as React from 'react'; +import Button from '@mui/material/Button'; +import DeleteIcon from '@mui/icons-material/Delete'; +import CheckIcon from '@mui/icons-material/Check'; +import Stack from '@mui/material/Stack'; + +export default function IntroButtons() { + return ( + + + + + + ); +} diff --git a/docs/data/material/components/buttons/OutlinedButtons.js b/docs/data/material/components/buttons/OutlinedButtons.js deleted file mode 100644 index 4c322ddf9b543d..00000000000000 --- a/docs/data/material/components/buttons/OutlinedButtons.js +++ /dev/null @@ -1,17 +0,0 @@ -import * as React from 'react'; -import Button from '@mui/material/Button'; -import Stack from '@mui/material/Stack'; - -export default function OutlinedButtons() { - return ( - - - - - - ); -} diff --git a/docs/data/material/components/buttons/OutlinedButtons.tsx b/docs/data/material/components/buttons/OutlinedButtons.tsx deleted file mode 100644 index 4c322ddf9b543d..00000000000000 --- a/docs/data/material/components/buttons/OutlinedButtons.tsx +++ /dev/null @@ -1,17 +0,0 @@ -import * as React from 'react'; -import Button from '@mui/material/Button'; -import Stack from '@mui/material/Stack'; - -export default function OutlinedButtons() { - return ( - - - - - - ); -} diff --git a/docs/data/material/components/buttons/OutlinedButtons.tsx.preview b/docs/data/material/components/buttons/OutlinedButtons.tsx.preview deleted file mode 100644 index fa5532b2840b06..00000000000000 --- a/docs/data/material/components/buttons/OutlinedButtons.tsx.preview +++ /dev/null @@ -1,7 +0,0 @@ - - - \ No newline at end of file diff --git a/docs/data/material/components/buttons/RippleButtons.js b/docs/data/material/components/buttons/RippleButtons.js new file mode 100644 index 00000000000000..cf76532f322c28 --- /dev/null +++ b/docs/data/material/components/buttons/RippleButtons.js @@ -0,0 +1,17 @@ +import * as React from 'react'; +import Stack from '@mui/material/Stack'; +import Button from '@mui/material/Button'; + +export default function RippleButtons() { + return ( + + + + + + ); +} diff --git a/docs/data/material/components/buttons/RippleButtons.tsx b/docs/data/material/components/buttons/RippleButtons.tsx new file mode 100644 index 00000000000000..cf76532f322c28 --- /dev/null +++ b/docs/data/material/components/buttons/RippleButtons.tsx @@ -0,0 +1,17 @@ +import * as React from 'react'; +import Stack from '@mui/material/Stack'; +import Button from '@mui/material/Button'; + +export default function RippleButtons() { + return ( + + + + + + ); +} diff --git a/docs/data/material/components/buttons/RippleButtons.tsx.preview b/docs/data/material/components/buttons/RippleButtons.tsx.preview new file mode 100644 index 00000000000000..8b3af2aec91abc --- /dev/null +++ b/docs/data/material/components/buttons/RippleButtons.tsx.preview @@ -0,0 +1,7 @@ + + + \ No newline at end of file diff --git a/docs/data/material/components/buttons/TextButtons.js b/docs/data/material/components/buttons/TextButtons.js deleted file mode 100644 index a1b001cdd59c01..00000000000000 --- a/docs/data/material/components/buttons/TextButtons.js +++ /dev/null @@ -1,13 +0,0 @@ -import * as React from 'react'; -import Button from '@mui/material/Button'; -import Stack from '@mui/material/Stack'; - -export default function TextButtons() { - return ( - - - - - - ); -} diff --git a/docs/data/material/components/buttons/TextButtons.tsx b/docs/data/material/components/buttons/TextButtons.tsx deleted file mode 100644 index a1b001cdd59c01..00000000000000 --- a/docs/data/material/components/buttons/TextButtons.tsx +++ /dev/null @@ -1,13 +0,0 @@ -import * as React from 'react'; -import Button from '@mui/material/Button'; -import Stack from '@mui/material/Stack'; - -export default function TextButtons() { - return ( - - - - - - ); -} diff --git a/docs/data/material/components/buttons/TextButtons.tsx.preview b/docs/data/material/components/buttons/TextButtons.tsx.preview deleted file mode 100644 index b21873401ea164..00000000000000 --- a/docs/data/material/components/buttons/TextButtons.tsx.preview +++ /dev/null @@ -1,3 +0,0 @@ - - - \ No newline at end of file diff --git a/docs/data/material/components/buttons/buttons.md b/docs/data/material/components/buttons/buttons.md index 35089bd278cab9..e6e472cae1a6e5 100644 --- a/docs/data/material/components/buttons/buttons.md +++ b/docs/data/material/components/buttons/buttons.md @@ -10,141 +10,147 @@ unstyled: /base-ui/react-button/ # Button -

Buttons allow users to take actions, and make choices, with a single tap.

- -Buttons communicate actions that users can take. They are typically placed throughout your UI, in places like: - -- Modal windows -- Forms -- Cards -- Toolbars +

Buttons enable users to take actions and make choices.

{{"component": "modules/components/ComponentLinkHeader.js"}} -## Basic button +## Introduction -The `Button` comes with three variants: text (default), contained, and outlined. - -{{"demo": "BasicButtons.js"}} +Buttons communicate actions that users can take. +The Material UI Button component replaces the native HTML ` -You can remove the elevation with the `disableElevation` prop. +// renders as -{{"demo": "DisableElevation.js"}} - -### Outlined button +Home +``` -[Outlined buttons](https://m2.material.io/components/buttons#outlined-button) are medium-emphasis buttons. -They contain actions that are important but aren't the primary action in an app. +### Variants -Outlined buttons are also a lower emphasis alternative to contained buttons, -or a higher emphasis alternative to text buttons. +The Button component supports three values for the `variant` prop: `text` (default), `contained`, and `outlined`. -{{"demo": "OutlinedButtons.js"}} +{{"demo": "BasicButtons.js"}} -## Handling clicks +#### Elevation -All components accept an `onClick` handler that is applied to the root DOM element. +Apply the `disableElevation` prop to remove the default drop shadow from the `contained` variant. -```jsx - -``` +{{"demo": "DisableElevation.js"}} -Note that the documentation [avoids](/material-ui/guides/api/#native-properties) mentioning native props (there are a lot) in the API section of the components. +### Colors -## Color +Every palette included in the theme is available via the `color` prop. {{"demo": "ColorButtons.js"}} -In addition to using the default button colors, you can add custom ones, or disable any you don't need. See the [Adding new colors](/material-ui/customization/palette/#custom-colors) examples for more info. +:::success +If the default colors aren't sufficient, you can add custom colors and remove defaults that you don't need. +See the [Palette—Custom colors](/material-ui/customization/palette/#custom-colors) doc for more info. +::: -## Sizes +### Sizes -For larger or smaller buttons, use the `size` prop. +The Button component comes in three sizes: `small`, `medium` (default), and `large`. {{"demo": "ButtonSizes.js"}} -## Buttons with icons and label +#### Width + +Use the `fullWidth` prop to stretch the Button to fill its container. + +{{"demo": "FullWidthButton.js"}} + +### Start and end icons -Sometimes you might want to have icons for certain buttons to enhance the UX of the application as we recognize logos more easily than plain text. For example, if you have a delete button you can label it with a dustbin icon. +Use the `startIcon` or `endIcon` prop to append an icon to the beginning or end of a Button's contents. {{"demo": "IconLabelButtons.js"}} -## Icon button +### Ripple effect -Icon buttons are commonly found in app bars and toolbars. +The ripple effect provides visual feedback to the user that the Button is being clicked or focused. +Use the `disableFocusRipple` prop to remove only the focus effect, or `disableRipple` to remove the ripple when focusing and clicking. -Icons are also appropriate for toggle buttons that allow a single choice to be selected or -deselected, such as adding or removing a star to an item. +:::warning +These props remove _all_ default styles from the `:focus-visible` state, which means the user won't have any visual indication that the Button is focused. +You can target the `.Mui-focusVisible` class to define your own styles for a better user experience. -{{"demo": "IconButtons.js"}} +The demo below shows what happens if you don't define custom styles for the focus state. +::: -### Sizes +{{"demo": "RippleButtons.js"}} -For larger or smaller icon buttons, use the `size` prop. +### Icon Buttons -{{"demo": "IconButtonSizes.js"}} +```jsx +import IconButton from '@mui/material/IconButton'; +``` -### Colors +Icon buttons are commonly found in app bars and toolbars. +They're also useful for toggle buttons that give the user a single choice to be selected or deselected, such as adding or removing a star to an item. -Use `color` prop to apply theme color palette to component. +The Material UI Icon Button component accepts the same props and values as the Button for [sizes](#sizes) and [colors](#colors). -{{"demo": "IconButtonColors.js"}} +{{"demo": "IconButtons.js"}} -## File upload +### Handling clicks -To create a file upload button, turn the button into a label using `component="label"` and then create a visually-hidden input with type `file`. +Material UI Buttons accept an `onClick` handler that's applied to the root DOM element. -{{"demo": "InputFileUpload.js"}} +```jsx + +``` -## Customization +#### Disable + +Use the `disabled` prop to disable clicking on a Button. -Here are some examples of customizing the component. -You can learn more about this in the [overrides documentation page](/material-ui/customization/how-to-customize/). +{{"demo": "DisabledButton.js"}} -{{"demo": "CustomizedButtons.js", "defaultCodeOpen": false}} +## Customization -🎨 If you are looking for inspiration, you can check [MUI Treasury's customization examples](https://mui-treasury.com/?path=/docs/button-introduction--docs). +### Button Base -## Complex button +```jsx +import ButtonBase from '@mui/material/ButtonBase'; +``` -The Text Buttons, Contained Buttons, Floating Action Buttons and Icon Buttons are built on top of the same component: the `ButtonBase`. -You can take advantage of this lower-level component to build custom interactions. +Material UI's Buttons are all built on top of the Button Base component. +You can take advantage of this lower-level component to create custom interactions, as shown in the demo below. {{"demo": "ButtonBaseDemo.js"}} -## Third-party routing library +#### Routing One frequent use case is to perform navigation on the client only, without an HTTP round-trip to the server. -The `ButtonBase` component provides the `component` prop to handle this use case. -Here is a [more detailed guide](/material-ui/integrations/routing/#button). +The Button Base component provides the `component` prop to handle this use case. +For more information, see the [Routing—Button](/material-ui/integrations/routing/#button) doc. -## Limitations +#### Limitations -### Cursor not-allowed +##### Cursor not-allowed -The ButtonBase component sets `pointer-events: none;` on disabled buttons, which prevents the appearance of a disabled cursor. +The Button Base component sets `pointer-events: none;` on disabled buttons, which prevents the appearance of a disabled cursor. If you wish to use `not-allowed`, you have two options: @@ -160,9 +166,9 @@ If you wish to use `not-allowed`, you have two options: However: - You should add `pointer-events: none;` back when you need to display [tooltips on disabled elements](/material-ui/react-tooltip/#disabled-elements). -- The cursor won't change if you render something other than a button element, for instance, a link `` element. +- The cursor won't change if you render something other than a button element—for instance, a link `` element. -2. **DOM change**. You can wrap the button: +2. **DOM change**. You can wrap the Button: ```jsx @@ -172,13 +178,25 @@ However: ``` -This has the advantage of supporting any element, for instance, a link `` element. +This has the advantage of supporting any element—for instance, a link `` element. + +## Common examples + +### File upload button + +To create a file upload button, turn the Button into a label using `component="label"` and then create a visually-hidden input with type `file`, as shown in the demo below: + +{{"demo": "InputFileUpload.js"}} ## Experimental APIs -### Loading button +### Loading Button + +```jsx +import LoadingButton from '@mui/lab/LoadingButton'; +``` -[`@mui/lab`](/material-ui/about-the-lab/) offers loading buttons that can show loading state and disable interactions. +The [`@mui/lab`](/material-ui/about-the-lab/) package offers a Loading Button component, which displays a loading state and disables interactions. {{"demo": "LoadingButtons.js"}}