# Icon Button Component

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

## Usage {#usage}

Import the component:

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

Import the TypeScript type:

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

Example:

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

## Examples {#examples}

### Icon {#example-icon}

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

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

### Shape {#example-variant}

The `variant` attribute determines the shape of the icon button.

```html
<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>
```

### Selectable {#example-selectable}

Add the `selectable` attribute to make the icon button selectable.

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

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.

```html
<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>
```

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.

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

### Link {#example-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.

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

### Disabled and Loading State {#example-disabled}

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

```html
<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>
```

## mdui-button-icon API

### Properties

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

### Methods

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

### Events

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>focus</td>
    <td><p>Emitted when the button gains focus.</p>
</td>
  </tr>
  <tr>
    <td>blur</td>
    <td><p>Emitted when the button loses focus.</p>
</td>
  </tr>
  <tr>
    <td>change</td>
    <td><p>Emitted when the selected state changes.</p>
</td>
  </tr>
  <tr>
    <td>invalid</td>
    <td><p>Emitted when the form control&#39;s validity is checked and it does not meet the constraints.</p>
</td>
  </tr>
</tbody>
</table>

### Slots

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>(default)</td>
    <td><p>Icon component.</p>
</td>
  </tr>
  <tr>
    <td>selected-icon</td>
    <td><p>Icon in the selected state.</p>
</td>
  </tr>
</tbody>
</table>

### CSS Parts

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>button</td>
    <td><p>Internal <code>&lt;button&gt;</code> or <code>&lt;a&gt;</code> element.</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td><p>Icon.</p>
</td>
  </tr>
  <tr>
    <td>selected-icon</td>
    <td><p>Icon in the selected state.</p>
</td>
  </tr>
  <tr>
    <td>loading</td>
    <td><p>The <code>&lt;mdui-circular-progress&gt;</code> element for the loading state.</p>
</td>
  </tr>
</tbody>
</table>

### CSS Custom Properties

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>--shape-corner</td>
    <td><p>The corner radius of the component. You can use a specific pixel value, but it is recommended to reference <a href="/en/docs/2/styles/design-tokens#shape-corner">design tokens</a>.</p>
</td>
  </tr>
</tbody>
</table>