## Button  
DMC alternative to html.Button.  
Category: Buttons  

### Introduction

### Variant

```python
import dash_mantine_components as dmc

component = dmc.Group(
    [
        dmc.Button("Default button"),
        dmc.Button("Subtle button", variant="subtle"),
        dmc.Button("Gradient button", variant="gradient"),
        dmc.Button("Filled button", variant="filled"),
        dmc.Button("Light button", variant="light"),
        dmc.Button("Outline button", variant="outline"),
        dmc.Button("Transparent", variant="transparent"),
        dmc.Button("White", variant="white"),
    ]
)
```
#### Gradient Variant

To use gradient as Button background:

* set `variant` prop to "gradient"
* set `gradient` prop to `{ 'from': 'color-from', 'to': 'color-to', 'deg': 135}`, where

  * `color-from` and `color-to` are colors from Mantine's theme colors.
  * `deg` is linear gradient deg.

```python
import dash_mantine_components as dmc

component = dmc.Group(
    children=[
        dmc.Button(
            "Indigo cyan",
            variant="gradient",
            gradient={"from": "indigo", "to": "cyan"},
        ),
        dmc.Button(
            "Lime green",
            variant="gradient",
            gradient={"from": "teal", "to": "lime", "deg": 105},
        ),
        dmc.Button(
            "Teal blue",
            variant="gradient",
            gradient={"from": "teal", "to": "blue", "deg": 60},
        ),
        dmc.Button(
            "Orange red",
            variant="gradient",
            gradient={"from": "orange", "to": "red"},
        ),
        dmc.Button(
            "Grape pink",
            variant="gradient",
            gradient={"from": "grape", "to": "pink", "deg": 35},
        ),
    ]
)
```
### Left and right sections  

`leftSection` and `rightSection` allow adding icons or any other element to the left and right side of the button.
When a section is added, padding on the corresponding side is reduced.

Note that `leftSection` and `rightSection` are flipped in RTL mode (`leftSection` is displayed on the right and `rightSection` is displayed on the left).

```python
import dash_mantine_components as dmc
from dash_iconify import DashIconify

component = dmc.Group(
    [
        dmc.Button(
            "Connect to Database",
            leftSection=DashIconify(icon="fluent:database-plug-connected-20-filled"),
        ),
        dmc.Button(
            "Load Data",
            variant="subtle",
            rightSection=DashIconify(icon="logos:twitter"),
            color="blue",
        ),
        dmc.Button(
            "Settings",
            variant="outline",
            leftSection=DashIconify(icon="fluent:settings-32-regular"),
        ),
    ]
)
```
### Sections position
`justify` prop sets `justify-content` of inner element. You can use it to change the alignment of left and right sections.
For example, to spread them across the button set `justify='space-between'`.

If you need to align just one section to the side of the button, set `justify` to `space-between` and add empty `html.Span()` to the opposite section.


```python
import dash_mantine_components as dmc
from dash_iconify import DashIconify
from dash import html

icon = DashIconify(icon="tabler:photo", width=14)

component = dmc.Stack(
    [
        dmc.Button(
            "Button label",
            justify="center",
            fullWidth=True,
            leftSection=icon,
            rightSection=icon,
            variant="default",
        ),
        dmc.Button(
            "Button label",
            justify="center",
            fullWidth=True,
            leftSection=icon,
            variant="default",
            mt="md",
        ),
        dmc.Button(
            "Button label",
            justify="center",
            fullWidth=True,
            rightSection=icon,
            variant="default",
            mt="md",
        ),
        dmc.Button(
            "Button label",
            justify="center",
            fullWidth=True,
            leftSection=html.Span(),  # Empty spacer
            rightSection=icon,
            variant="default",
            mt="md",
        ),
    ]
)
```

### Loading State

Starting with dash version 2.9.2, you can use duplicate callback outputs. Here's an example that lets you easily show
loading state while the callback is running.   Note that the button is disabled automatically when `loading=True`

```python
import uuid
from time import sleep

import dash_mantine_components as dmc
from dash import html, callback, Output, Input, clientside_callback
from dash_iconify import DashIconify

component = html.Div(
    [
        dmc.Button(
            "Load from database",
            id="loading-button",
            leftSection=DashIconify(icon="fluent:database-plug-connected-20-filled"),
        ),
        dmc.Text(id="clicked-output", mt=10),
    ]
)

clientside_callback(
    """
    function updateLoadingState(n_clicks) {
        return true
    }
    """,
    Output("loading-button", "loading", allow_duplicate=True),
    Input("loading-button", "n_clicks"),
    prevent_initial_call=True,
)


@callback(
    Output("clicked-output", "children"),
    Output("loading-button", "loading"),
    Input("loading-button", "n_clicks"),
    prevent_initial_call=True,
)
def load_from_db(n_clicks):
    sleep(3)
    return str(uuid.uuid4()), False
```
### Loader Props

You can customize [Loader](/components/loader) with `loaderProps` prop, it accepts all props that Loader component has:

```python
import dash_mantine_components as dmc

component = dmc.Button("Loading Props", loaderProps={"type": "dots"}, loading=True)
```
### Colors

```python
import dash_mantine_components as dmc

dmc.Button("Settings", color="red")
```

### Radius and Size

Button's radius and size can be customized by setting `radius` and `size` props. Both props have predefined values:
xs, sm, md, lg, xl. Alternatively, you can use a number to set radius, size in px.

```python
import dash_mantine_components as dmc

dmc.Group(
    [
        dmc.Button("Connect to Database", size="sm"),
        dmc.Button("Notify", radius="xl"),
        dmc.Button("Settings", size=20),
    ]
)
```

### Compact Size

```python
import dash_mantine_components as dmc

sizes = ["xs", "sm", "md", "lg", "xl"]

component = dmc.Stack(
    [
        dmc.Group(
            [dmc.Button(f"Normal {size}", size=size) for size in sizes],
        ),
        dmc.Group(
            [dmc.Button(f"Compact {size}", size=f"compact-{size}") for size in sizes],
        ),
    ]
)
```
### Full Width Button

Pass `fullWidth=True` for a full width button.

```python
import dash_mantine_components as dmc

component = dmc.Button("Click to open the app", fullWidth=True, variant="outline")
```
### Add custom variants

To add new `Button` variants, define a class in the `.css` file using the `data-variant` attribute. Add the new variants to
the `theme` prop in the `MantineProvider` so they available in all `Button` components in your app.


Example:
 - [View Code on GitHub](https://github.com/snehilvj/dmc-docs/tree/main/help_center/theme/button_custom_variants.py)  
 - [Live Demo on PyCafe](https://py.cafe/dash.mantine.components/button-custom-variants-demo-0)  
 

The example includes the following in a .css file in /assets
```css
.button-custom-variants {
  &[data-variant='danger'] {
    background-color: var(--mantine-color-red-9);
    color: var(--mantine-color-red-0);
  }

  &[data-variant='primary'] {
    background: linear-gradient(45deg, #4b6cb7 10%, #253b67 90%);
    color: var(--mantine-color-white);
    border-width: 0;
  }
}
```

The example adds the custom variants to the `theme` prop in `Mantine Provider`

```python
app.layout = dmc.MantineProvider(
   children=[# your app content],
   theme={
      "components": {
           "Button": {"classNames": {"root": "button-custom-variants"}}
       }
   }
)
```


### Button Group

```python
import dash_mantine_components as dmc

component = dmc.ButtonGroup(
    [
        dmc.Button("First", variant="outline"),
        dmc.Button("Second", variant="outline"),
        dmc.Button("Third", variant="outline"),
    ]
)
```
Note that you must not wrap child `Button` components with any additional elements:

```python
dmc.ButtonGroup([
    html.Div(dmc.Button("This will not work")),
    dmc.Button("Buttons will have incorrect borders")
])
```

### Styles API


This component supports Styles API. With Styles API, you can customize styles of any inner element. See the Styling and Theming sections of these docs for more information.


#### Button Selectors

| Selector | Static selector          | Description                                        |
|----------|---------------------------|----------------------------------------------------|
| root     | .mantine-Button-root      | Root element                                       |
| loader   | .mantine-Button-loader    | Loader component, displayed only when `loading` prop is set |
| inner    | .mantine-Button-inner     | Contains all other elements, child of the root element |
| section  | .mantine-Button-section   | Left and right sections of the button             |
| label    | .mantine-Button-label     | Button children                                   |

#### Button CSS Variables

| Selector | Variable                  | Description                                       |
|----------|---------------------------|---------------------------------------------------|
| root     | --button-bg               | Controls background                               |
|          | --button-bd               | Controls border                                   |
|          | --button-hover            | Controls background when hovered                 |
|          | --button-color            | Controls text color                               |
|          | --button-hover-color      | Controls text color when hovered                 |
|          | --button-radius           | Controls border-radius                            |
|          | --button-height           | Controls height of the button                     |
|          | --button-padding-x        | Controls horizontal padding of the button         |
|          | --button-fz               | Controls font-size of the button                  |
|          | --button-justify          | Controls `justify-content` of the inner element   |

#### Button Data Attributes

| Selector       | Attribute             | Condition               | Value                           |
|----------------|------------------------|--------------------------|---------------------------------|
| root           | data-disabled          | `disabled` prop is set   | –                               |
| root, label    | data-loading           | `loading` prop is set    | –                               |
| root           | data-block             | `fullWidth` prop is set  | –                               |
| root           | data-with-left-section | `leftSection` is set     | –                               |
| root           | data-with-right-section| `rightSection` is set    | –                               |
| section        | data-position          | –                        | Section position: left or right |

#### Button.Group Selectors

| Selector | Static selector            | Description               |
|----------|-----------------------------|---------------------------|
| group    | .mantine-ButtonGroup-group  | Root element              |

#### Button.Group CSS Variables

| Selector | Variable                  | Description                               |
|----------|---------------------------|-------------------------------------------|
| group    | --button-border-width     | Border-width of child Button components   |

#### Button.Group Data Attributes

| Selector | Attribute        | Value                   |
|----------|-------------------|-------------------------|
| group    | data-orientation  | Value of `orientation` prop |




### Keyword Arguments
#### Button

- children (a list of or a singular dash component, string or number; optional):
    Button content.

- id (string; optional):
    Unique ID to identify this component in Dash callbacks.

- aria-* (string; optional):
    Wild card aria attributes.

- attributes (boolean | number | string | dict | list; optional):
    Passes attributes to inner elements of a component.  See Styles
    API docs.

- autoContrast (boolean; optional):
    Determines whether button text color with filled variant should
    depend on `background-color`. If luminosity of the `color` prop is
    less than `theme.luminosityThreshold`, then `theme.white` will be
    used for text color, otherwise `theme.black`. Overrides
    `theme.autoContrast`.

- className (string; optional):
    Class added to the root element, if applicable.

- classNames (dict; optional):
    Adds custom CSS class names to inner elements of a component.  See
    Styles API docs.

- color (optional):
    Key of `theme.colors` or any valid CSS color, `theme.primaryColor`
    by default.

- darkHidden (boolean; optional):
    Determines whether component should be hidden in dark color scheme
    with `display: none`.

- data-* (string; optional):
    Wild card data attributes.

- disabled (boolean; optional):
    Indicates disabled state.

- fullWidth (boolean; optional):
    Determines whether button should take 100% width of its parent
    container, `False` by default.

- gradient (dict; optional):
    Gradient configuration used when `variant="gradient"`, default
    value is `theme.defaultGradient`.

    `gradient` is a dict with keys:

- hiddenFrom (string; optional):
    Breakpoint above which the component is hidden with `display:
    none`.

- justify (optional):
    Sets `justify-content` of `inner` element, can be used to change
    distribution of sections and label, `'center'` by default.

- leftSection (a list of or a singular dash component, string or number; optional):
    Content displayed on the left side of the button label.

- lightHidden (boolean; optional):
    Determines whether component should be hidden in light color
    scheme with `display: none`.

- loaderProps (dict; optional):
    Props added to the `Loader` component (only visible when `loading`
    prop is set).

    `loaderProps` is a dict with keys:

- loading (boolean; optional):
    Determines whether the `Loader` component should be displayed over
    the button.

- loading_state (dict; optional):
    Object that holds the loading state object coming from
    dash-renderer. For use with dash<3.

    `loading_state` is a dict with keys:

- mod (string | dict | list of string | dicts; optional):
    Element modifiers transformed into `data-` attributes. For
    example: "xl" or {"data-size": "xl"}. Can also be a list of
    strings or dicts for multiple modifiers. Falsy values are removed.

- n_clicks (number; default 0):
    An integer that represents the number of times that this element
    has been clicked on.

- radius (number; optional):
    Key of `theme.radius` or any valid CSS value to set
    `border-radius`, `theme.defaultRadius` by default.

- rightSection (a list of or a singular dash component, string or number; optional):
    Content displayed on the right side of the button label.

- size (optional):
    Controls button `height`, `font-size` and horizontal `padding`,
    `'sm'` by default.

- styles (boolean | number | string | dict | list; optional):
    Adds inline styles directly to inner elements of a component.  See
    Styles API docs.

- tabIndex (number; optional):
    tab-index.

- variant (string; optional):
    variant.

- visibleFrom (string; optional):
    Breakpoint below which the component is hidden with `display:
    none`.
#### ButtonGroup

- children (a list of or a singular dash component, string or number; optional):
    `Button` components.

- id (string; optional):
    Unique ID to identify this component in Dash callbacks.

- aria-* (string; optional):
    Wild card aria attributes.

- attributes (boolean | number | string | dict | list; optional):
    Passes attributes to inner elements of a component.  See Styles
    API docs.

- borderWidth (string | number; optional):
    `border-width` of the child `Button` components. Numbers are
    converted to rem. Default value in `1`.

- className (string; optional):
    Class added to the root element, if applicable.

- classNames (dict; optional):
    Adds custom CSS class names to inner elements of a component.  See
    Styles API docs.

- darkHidden (boolean; optional):
    Determines whether component should be hidden in dark color scheme
    with `display: none`.

- data-* (string; optional):
    Wild card data attributes.

- hiddenFrom (string; optional):
    Breakpoint above which the component is hidden with `display:
    none`.

- lightHidden (boolean; optional):
    Determines whether component should be hidden in light color
    scheme with `display: none`.

- loading_state (dict; optional):
    Object that holds the loading state object coming from
    dash-renderer. For use with dash<3.

    `loading_state` is a dict with keys:

- mod (string | dict | list of string | dicts; optional):
    Element modifiers transformed into `data-` attributes. For
    example: "xl" or {"data-size": "xl"}. Can also be a list of
    strings or dicts for multiple modifiers. Falsy values are removed.

- orientation (a value equal to: 'horizontal', 'vertical'; optional):
    Orientation of the group, `horizontal` by default.

- styles (boolean | number | string | dict | list; optional):
    Adds inline styles directly to inner elements of a component.  See
    Styles API docs.

- tabIndex (number; optional):
    tab-index.

- variant (string; optional):
    variant.

- visibleFrom (string; optional):
    Breakpoint below which the component is hidden with `display:
    none`.