ButtonIcon

Icon buttons are used to perform small actions with a single click.

Usage

Import the component:

import 'mdui/components/button-icon.js';

Import the TypeScript type:

import type { ButtonIcon } from 'mdui/components/button-icon.js';

Example:

<mdui-button-icon icon="search"></mdui-button-icon>

Examples

Icon

Use the icon attribute to specify the Material Icon name. Alternatively, you can use the default slot to specify the icon element.

<mdui-button-icon icon="search"></mdui-button-icon>
<mdui-button-icon>
  <mdui-icon name="search"></mdui-icon>
</mdui-button-icon>

Source

Shape

The variant attribute determines the shape of the icon button.

<mdui-button-icon variant="standard" icon="search"></mdui-button-icon>
<mdui-button-icon variant="filled" icon="search"></mdui-button-icon>
<mdui-button-icon variant="tonal" icon="search"></mdui-button-icon>
<mdui-button-icon variant="outlined" icon="search"></mdui-button-icon>

Source

Selectable

Add the selectable attribute to make the icon button selectable.

<mdui-button-icon selectable icon="favorite_border"></mdui-button-icon>

Source

Use the selected-icon attribute to specify the Material Icon name for the selected state. Alternatively, use the selected-icon slot to specify the selected state icon element.

<mdui-button-icon selectable icon="favorite_border" selected-icon="favorite"></mdui-button-icon>
<mdui-button-icon selectable icon="favorite_border">
  <mdui-icon slot="selected-icon" name="favorite"></mdui-icon>
</mdui-button-icon>

Source

The selected property is true when the icon button is selected. Add the selected attribute to set the icon button to the selected state by default.

<mdui-button-icon selectable selected icon="favorite_border" selected-icon="favorite"></mdui-button-icon>

Source

Link

Use the href attribute to turn the icon button into a link. The download, target, and rel attributes are available for link-related functionality.

<mdui-button-icon icon="search" href="https://www.mdui.org" target="_blank"></mdui-button-icon>

Source

Disabled and Loading State

Use the disabled attribute to disable the icon button. The loading attribute shows the loading state.

<mdui-button-icon disabled icon="search" variant="tonal"></mdui-button-icon>
<mdui-button-icon loading icon="search" variant="tonal"></mdui-button-icon>
<mdui-button-icon loading disabled icon="search" variant="tonal"></mdui-button-icon>

Source

API

Properties

Attribute	Property	Type	Default
`variant`	`variant`	`'standard' \| 'filled' \| 'tonal' \| 'outlined'`	`'standard'`
Defines the icon button variant. Possible values: `standard`: For low-priority actions. `filled`: Has the strongest visual emphasis and works well for high-priority actions. `tonal`: Blends `filled` and `outlined`, and works well for medium- to high-priority actions. `outlined`: For medium-priority or secondary actions.
`icon`	`icon`	`string`	-
Specifies the Material Icons name. Alternatively, use the default slot.
`selected-icon`	`selectedIcon`	`string`	-
Specifies the Material Icons name when selected. Alternatively, use `slot="selected-icon"`.
`selectable`	`selectable`	`boolean`	`false`
Makes the button selectable.
`selected`	`selected`	`boolean`	`false`
Indicates whether the button is selected.
`href`	`href`	`string`	-
The URL for the link. When set, the component renders as an `<a>` element and supports link-related attributes.
`download`	`download`	`string`	-
Downloads the linked URL. Note: Only available when `href` is specified.
`target`	`target`	`'_blank' \| '_parent' \| '_self' \| '_top'`	-
Controls where the linked URL opens. Possible values: `_blank`: Opens in a new tab or window. `_parent`: Opens in the parent browsing context, or `_self` if there is no parent. `_self`: Opens in the current browsing context (default). `_top`: Opens in the topmost browsing context, or `_self` if there are no ancestors. Note: Only available when `href` is specified.
`rel`	`rel`	`'alternate' \| 'author' \| 'bookmark' \| 'external' \| 'help' \| 'license' \| 'me' \| 'next' \| 'nofollow' \| 'noreferrer' \| 'opener' \| 'prev' \| 'search' \| 'tag'`	-
Specifies the relationship of the linked URL as space-separated link types. Possible values: `alternate`: An alternate version of the current document. `author`: The author of the current document or article. `bookmark`: The permalink for the nearest ancestor section. `external`: The referenced document is not part of the same site as the current document. `help`: A link to context-sensitive help. `license`: Content covered by the copyright license described by the referenced document. `me`: Links to content owned by the current document's author. `next`: The next document in the series. `nofollow`: Not endorsed by the original author or publisher. `noreferrer`: Prevents the `Referer` header from being sent. Same effect as `noopener`. `opener`: Creates an auxiliary browsing context if the hyperlink would otherwise create a top-level browsing context that is not an auxiliary one (i.e., when `target="_blank"`). `prev`: The previous document in the series. `search`: Links to a resource that can be used to search through the current document and its related pages. `tag`: Marks the current document with the given tag. Note: Only available when `href` is specified.
`autofocus`	`autofocus`	`boolean`	`false`
Whether the element is focused when the page loads.
`tabindex`	`tabIndex`	`number`	-
The element's tab order when navigating with the Tab key.
`disabled`	`disabled`	`boolean`	`false`
Disables the element.
`loading`	`loading`	`boolean`	`false`
Indicates that the element is in a loading state.
`name`	`name`	`string`	`''`
The button name submitted with form data. Note: Only available when `href` is not specified.
`value`	`value`	`string`	`''`
The button value submitted with form data. Note: Only available when `href` is not specified.
`type`	`type`	`'submit' \| 'reset' \| 'button'`	`'button'`
Specifies the button's default action. Default: `button`. Possible values: `submit`: Submits the form data to the server. `reset`: Restores all controls to their initial values. `button`: Does nothing by default. Note: Only available when `href` is not specified.
`form`	`form`	`string`	-
Associates the button with a `<form>` element. Set this to the `id` of a `<form>` in the same document. If omitted, the button uses its parent `<form>`, if any. This lets the button target any form in the document, not just the one it is nested in. Note: Only available when `href` is not specified.
`formaction`	`formAction`	`string`	-
Specifies the URL that processes the button's submitted information. Overrides the `action` attribute of the button's form owner. Note: Only available when `href` is not specified and `type="submit"`.
`formenctype`	`formEnctype`	`'application/x-www-form-urlencoded' \| 'multipart/form-data' \| 'text/plain'`	-
Specifies how to encode the form data. Possible values: `application/x-www-form-urlencoded`: Default when the attribute is omitted. `multipart/form-data`: Used for `<input>` elements with `type="file"`. `text/plain`: Useful for debugging, but not for actual form submissions. Overrides the `enctype` attribute of the button's form owner. Note: Only available when `href` is not specified and `type="submit"`.
`formmethod`	`formMethod`	`'post' \| 'get'`	-
Specifies the HTTP method for form submission. Possible values: `post`: Sends the form data in the request body. `get`: Appends the form data to the `action` URL. Overrides the `method` attribute of the button's form owner. Note: Only available when `href` is not specified and `type="submit"`.
`formnovalidate`	`formNoValidate`	`boolean`	`false`
Specifies that the form should not be validated on submission. Overrides the `novalidate` attribute of the button's form owner. Note: Only available when `href` is not specified and `type="submit"`.
`formtarget`	`formTarget`	`'_self' \| '_blank' \| '_parent' \| '_top'`	-
Specifies where to open the response after form submission. Possible values: `_self`: Current browsing context (default). `_blank`: New tab or window. `_parent`: Parent browsing context, or `_self` if there is no parent. `_top`: Topmost browsing context, or `_self` if there are no ancestors. Overrides the `target` attribute of the button's form owner. Note: Only available when `href` is not specified and `type="submit"`.
	`validity`	`ValidityState`	-
A `ValidityState` object that represents the element's validity states.
	`validationMessage`	`string`	-
The validation message. Returns an empty string when the element is valid.

Methods

Name	Parameters	Returns
`click`		`void`
Simulates a mouse click on the element.
`focus`	`options: FocusOptions` (Optional)	`void`
Sets focus on the element. An optional object parameter may include a `preventScroll` property. If `preventScroll` is set to `true`, the page will not scroll to bring the focused element into view.
`blur`		`void`
Removes focus from the element.
`checkValidity`		`boolean`
Checks the validity of the form field. If it is invalid, it triggers an `invalid` event and returns `false`. If valid, it returns `true`.
`reportValidity`		`boolean`
Checks the validity of the form field. If it is invalid, it triggers an `invalid` event, returns `false`, and displays a validation message. If valid, it returns `true`.
`setCustomValidity`	`message: string`	`void`
Sets a custom error message. If the message is non-empty, the field is considered invalid.

Events

Name
`focus`
Emitted when the button gains focus.
`blur`
Emitted when the button loses focus.
`change`
Emitted when the selected state changes.
`invalid`
Emitted when the form control's validity is checked and it does not meet the constraints.

Slots

Name
(default)
Icon component.
`selected-icon`
Icon in the selected state.

CSS Parts

Name
`button`
Internal `<button>` or `<a>` element.
`icon`
Icon.
`selected-icon`
Icon in the selected state.
`loading`
The `<mdui-circular-progress>` element for the loading state.

CSS Custom Properties

Name
`--shape-corner`
The corner radius of the component. You can use a specific pixel value, but it is recommended to reference design tokens.

Button

Card