## ActionIcon Use this component as an alternative to buttons when you just want to use an icon. Category: Buttons ### Introduction ### Usage ActionIcon component is an alternative to [Button](/components/button) component. It can be customized with Mantine styles and used with its `n_clicks` property. ```python import dash_mantine_components as dmc from dash import callback, html, Output, Input from dash_iconify import DashIconify component = html.Div( [ dmc.ActionIcon( DashIconify(icon="clarity:settings-line", width=20), size="lg", variant="filled", id="action-icon", n_clicks=0, mb=10, ), dmc.Text(id="action-output"), ] ) @callback( Output("action-output", "children"), Input("action-icon", "n_clicks"), ) def update_clicks(n_clicks): return f"Clicked {n_clicks} times." ``` ### Children You can use a dash component such as `DashIconify` in the `children` prop. Note that it does not control the icon size, you need to specify it manually on icon component to match `ActionIcon` size. For example, if you were to use `DashIconify`, you can set the icon size like this: ```python import dash_mantine_components as dmc from dash_iconify import DashIconify dmc.ActionIcon( DashIconify(icon="bi:github", width=20), size="lg" ) ``` ### Variants ```python import dash_mantine_components as dmc from dash_iconify import DashIconify component = dmc.Group( [ dmc.ActionIcon( DashIconify(icon="clarity:settings-line"), color="blue", variant=variant ) for variant in [ "subtle", "filled", "outline", "light", "default", "transparent", "gradient", "white" ] ] ) ``` ### Gradient variant When `variant` prop is set to `gradient`, you can control gradient with gradient prop, it accepts an object with `from`, `to` and `deg` properties. If the `gradient` prop is not set, `ActionIcon` will use `defaultGradient` which can be configured on the `theme` dict in the `MantineProvider`. `gradient` prop is ignored when `variant` is not set to `gradient`. Note that `variant="gradient"` supports only linear gradients with two colors. If you need a more complex gradient, then use `Styles API` to modify `ActionIcon` styles. ```python import dash_mantine_components as dmc from dash_iconify import DashIconify component = dmc.Group( [ dmc.ActionIcon( DashIconify(icon="clarity:settings-line"), color="blue", variant="gradient", gradient=gradient ) for gradient in [ {"from": "red", "to": "blue", "deg": 90 }, {"from": "red", "to": "blue", "deg": 180}, {"from": "teal", "to": "yellow", "deg": 90}, {"from": "teal", "to": "yellow", "deg": 180} ] ] ) ``` ### Colors Here is a sample using the following colors: "gray", "red", "pink", "grape", "violet", "indigo", "blue", "lime", "yellow", "orange" And these variants: "subtle", "filled", "outline", "light", "transparent" ```python import dash_mantine_components as dmc from dash_iconify import DashIconify dmc.ActionIcon( DashIconify(icon="icomoon-free:sun"), variant="outline", color="orange", ) ``` ### Size You can use any valid CSS value in `size` prop, it is used to set `width`, `min-width`, `min-height` and `height` properties. Note that `size` prop does not control child icon size, you need to set it manually on icon component. When size is a number, the value is treated as `px` units and converted to `rem` units. ```python dmc.ActionIcon(size=20, children=[...]) ``` If you want `ActionIcon` to have the same size as Mantine inputs, use `size="input-sm"` prop: ```python import dash_mantine_components as dmc component = dmc.Group([ dmc.TextInput(placeholder="sm sixe input", size="sm"), dmc.ActionIcon( size="input-sm", variant="default", children="SM" ) ]) ``` ### Loading state When `loading` prop is set, `ActionIcon` will be disabled and `Loader` with overlay will be rendered in the center of the button. Loader color depends on `ActionIcon` variant. ```python import dash_mantine_components as dmc from dash_iconify import DashIconify from dash import callback, Input, Output component = dmc.Box([ dmc.Group( [ dmc.ActionIcon( id="icon-loading-default", children=DashIconify(icon="tabler:heart", width=18, height=18) ), dmc.ActionIcon( id="icon-loading-light", children=DashIconify(icon="tabler:heart", width=18, height=18), variant="light", ), dmc.ActionIcon( id="icon-loading-outline", children=DashIconify(icon="tabler:heart", width=18, height=18), variant="outline", ), ] ), dmc.Switch( id="loading-switch", label="Loading state", checked=False, mt="md", ), ]) @callback( Output("icon-loading-default", "loading"), Output("icon-loading-light", "loading"), Output("icon-loading-outline", "loading"), Input("loading-switch", "checked"), ) def toggle_loading(loading_state): return loading_state, loading_state, loading_state ``` ### Loader props You can customize Loader with `loaderProps` prop, it accepts all props that `Loader` component has: ```python import dash_mantine_components as dmc component = dmc.ActionIcon(size="xl", loading=True, loaderProps={"type": "dots"}) ``` ### Add custom variants To add new `ActionIcon` 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 `ActionIcon` components in your app. Example: - [View Code on GitHub](https://github.com/snehilvj/dmc-docs/tree/main/help_center/theme/action_icon_custom_variants.py) - [Live Demo on PyCafe](https://py.cafe/dash.mantine.components/actionicon-custom-variants-demo) The example includes the following in a .css file in /assets ```css .ai-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); } } ``` The example adds the custom variants to the `theme` prop in `Mantine Provider` ```python app.layout = dmc.MantineProvider( children=[# your app content], theme={ "components": { "ActionIcon": {"classNames": {"root": "ai-custom-variants"}} } } ) ``` ### autoContrast `ActionIcon` supports `autoContrast` prop. You can also set `autoContrast` in the `theme` prop in the `MantineProvider`. If `autoContrast` is set either on `ActionIcon` or on `theme`, content color will be adjusted to have sufficient contrast with the value specified in `color` prop. Note that `autoContrast` feature works only if you use `color` prop to change background color. `autoContrast` works only with `filled` variant. ```python import dash_mantine_components as dmc from dash_iconify import DashIconify component = dmc.Group( [ dmc.ActionIcon( children=DashIconify(icon="tabler:heart", width=18, height=18), color="lime.3" ), dmc.ActionIcon( children=DashIconify(icon="tabler:heart", width=18, height=18), color="lime.3", autoContrast=True ), ] ) ``` ### ActionIconGroup ```python dmc.ActionIconGroup( [ dmc.ActionIcon( variant="default", size="lg", children=DashIconify(icon="tabler:photo", width=20), ), dmc.ActionIcon( variant="default", size="lg", children=DashIconify(icon="tabler:settings", width=20), ), dmc.ActionIcon( variant="default", size="lg", children=DashIconify(icon="tabler:heart", width=20), ), ], orientation="horizontal" ) ``` Note that you must not wrap child `ActionIcon` components with any additional elements: ```python dmc.ActionIconGroup([ html.Div(dmc.ActionIcon(...)), # don't do it like this dmc.ActionIcon(...) ]) ``` ### 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. #### ActionIcon Selectors | Selector | Static selector | Description | |----------|--------------------------------|------------------------------------------------------------| | root | .mantine-ActionIcon-root | Root element | | loader | .mantine-ActionIcon-loader | Loader component, rendered inside the root element when `loading` prop is set | | icon | .mantine-ActionIcon-icon | Inner icon wrapper | #### ActionIcon CSS Variables | Selector | Variable | Description | |----------|-----------------|----------------------------------------------| | root | --ai-bg | Controls background | | | --ai-hover | Controls background when hovered | | | --ai-bd | Controls border | | | --ai-color | Controls icon color | | | --ai-hover-color| Controls icon color when hovered | | | --ai-radius | Controls border-radius | | | --ai-size | Controls width, height, min-width, and min-height styles | #### ActionIcon Data Attributes | Selector | Attribute | Condition | |---------------|-----------------|----------------------------| | root | data-disabled | `disabled` prop is set | | root, icon | data-loading | `loading` prop is set | #### ActionIconGroup Selectors | Selector | Static selector | Description | |----------|-------------------------------------|---------------------------------| | group | .mantine-ActionIconGroup-group | Root element | #### ActionIconGroup CSS Variables | Selector | Variable | Description | |----------|---------------------|------------------------------------------------------------------| | group | --ai-border-width | Controls border width of child `ActionIcon` components placed beside one another | #### ActionIconGroup Data Attributes | Selector | Attribute | Value | |----------|------------------|----------------------------| | group | data-orientation | Value of `orientation` prop | ### Keyword Arguments #### ActionIcon - children (a list of or a singular dash component, string or number; optional): Icon displayed inside the button. - 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. Default value is `theme.primaryColor`. - 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): Sets `disabled` and `data-disabled` attributes on the button element. - gradient (dict; optional): Gradient data 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`. - 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 `Loader` component should be displayed instead of the `children`, `False` by default. - 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. Numbers are converted to rem. `theme.defaultRadius` by default. - size (number; optional): Controls width and height of the button. Numbers are converted to rem. `'md'` 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`. #### ActionIcon Group - children (a list of or a singular dash component, string or number; optional): `ActionIcon` components only. - 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 `ActionIcon` components. 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): Controls group orientation, `'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`.