# Button Component

Buttons are interactive components that enable users to execute actions such as sending emails, sharing documents, or expressing preferences.

## Usage {#usage}

Import the component:

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

Import the TypeScript type:

```ts
import type { Button } from 'mdui/components/button.js';
```

Example:

```html
<mdui-button>Button</mdui-button>
```

## Examples {#examples}

### Variant {#example-variant}

The `variant` attribute determines the button's appearance.

```html
<mdui-button variant="elevated">Elevated</mdui-button>
<mdui-button variant="filled">Filled</mdui-button>
<mdui-button variant="tonal">Tonal</mdui-button>
<mdui-button variant="outlined">Outlined</mdui-button>
<mdui-button variant="text">Text</mdui-button>
```

### Full Width {#example-full-width}

Add the `full-width` attribute to make the button span the entire width of its container.

```html
<mdui-button full-width>Button</mdui-button>
```

### Icons {#example-icon}

Use the `icon` and `end-icon` attributes to add Material Icons to the left and right sides of the button, respectively. Alternatively, use the `icon` and `end-icon` slots to add custom elements to the button's sides.

```html
<mdui-button icon="search" end-icon="arrow_forward">Icon</mdui-button>
<mdui-button>
  Slot
  <mdui-icon slot="icon" name="downloading"></mdui-icon>
  <mdui-icon slot="end-icon" name="attach_file"></mdui-icon>
</mdui-button>
```

### Link {#example-link}

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

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

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

Use the `disabled` attribute to disable the button. The `loading` attribute displays a loading state.

```html
<mdui-button disabled>Disabled</mdui-button>
<mdui-button loading>Loading</mdui-button>
<mdui-button loading disabled>Loading & Disabled</mdui-button>
```

## mdui-button 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;elevated&#39; | &#39;filled&#39; | &#39;tonal&#39; | &#39;outlined&#39; | &#39;text&#39;</td>
    <td>'filled'</td>
    <td><p>Defines the button style. Possible values:</p>
<ul>
<li><code>elevated</code>: A shadowed button for visual distinction.</li>
<li><code>filled</code>: Used for final actions like &#39;Save&#39; or &#39;Confirm&#39;.</li>
<li><code>tonal</code>: A mix between <code>filled</code> and <code>outlined</code>, suitable for medium to high-priority actions.</li>
<li><code>outlined</code>: A bordered button for medium-priority and secondary actions.</li>
<li><code>text</code>: A text button for low-priority actions.</li>
</ul>
</td>
  </tr>
  <tr>
    <td>full-width</td>
    <td>fullWidth</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>If set, the button will fill the width of its parent element.</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td>icon</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Specifies the Material Icons name on the left. Alternatively, use <code>slot=&quot;icon&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>end-icon</td>
    <td>endIcon</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Specifies the Material Icons name on the right. Alternatively, use <code>slot=&quot;end-icon&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>href</td>
    <td>href</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>The URL for the hyperlink. If provided, the component is rendered as an <code>&lt;a&gt;</code> element and can use link-related attributes.</p>
</td>
  </tr>
  <tr>
    <td>download</td>
    <td>download</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Instructs the browser to download the linked URL.</p>
<p><strong>Note</strong>: This is 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>Defines where to open the linked URL. 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 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 no ancestors.</li>
</ul>
<p><strong>Note</strong>: This is 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>: Alternate versions 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>: Indicates that the main content of the current document is covered by the copyright license described by the referenced document.</li>
<li><code>me</code>: Indicates that the current document represents the person who owns the linked content.</li>
<li><code>next</code>: Indicates that the current document is part of a series and the next document in the series is the referenced document.</li>
<li><code>nofollow</code>: Indicates that the current document&#39;s original author or publisher does not endorse the referenced document.</li>
<li><code>noreferrer</code>: No <code>Referer</code> header will be included. Also has the 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 browsing context (i.e., has &quot;<code>_blank</code>&quot; as <code>target</code> attribute value).</li>
<li><code>prev</code>: Indicates that the current document is part of a series and the previous document in the series is the referenced document.</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>: Gives a tag (identified by the given address) that applies to the current document.</li>
</ul>
<p><strong>Note</strong>: This is 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>Specifies that the element should be 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>Defines the order in which the element receives focus 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&#39;s name, which is submitted with form data.</p>
<p><strong>Note</strong>: This is 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&#39;s value, which is submitted with form data.</p>
<p><strong>Note</strong>: This is 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>Defines the button&#39;s default behavior. The default is <code>button</code>. Possible values:</p>
<ul>
<li><code>submit</code>: Submits the form data to the server.</li>
<li><code>reset</code>: Resets all the controls to their initial values.</li>
<li><code>button</code>: No default behavior, does nothing when pressed by default.</li>
</ul>
<p><strong>Note</strong>: This is 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. The value should be the <code>id</code> of a <code>&lt;form&gt;</code> in the same document. If not set, the button is associated with its parent <code>&lt;form&gt;</code>, if any.</p>
<p>This attribute allows button elements to be associated with <code>&lt;form&gt;</code>s anywhere in the document, not just inside a <code>&lt;form&gt;</code>.</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 the form data encoding method. Possible values:</p>
<ul>
<li><code>application/x-www-form-urlencoded</code>: Default if the attribute is not used.</li>
<li><code>multipart/form-data</code>: Used for <code>&lt;input&gt;</code> elements with <code>type</code> set to <code>file</code>.</li>
<li><code>text/plain</code>: For debugging, not for real form submission.</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>: Form data included in HTTP request body.</li>
<li><code>get</code>: Form data appended to <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 display the form submission response. 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 no parent.</li>
<li><code>_top</code>: Topmost browsing context or <code>_self</code> if 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 element&#39;s validation message. This is empty if the element meets its constraints.</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 parameter can be an object with 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&#39;s invalid, it triggers an <code>invalid</code> event and returns <code>false</code>. If it&#39;s 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&#39;s invalid, it triggers an <code>invalid</code> event, returns <code>false</code>, and displays a validation message. If it&#39;s 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 text is non-empty, it indicates that the field is 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>invalid</td>
    <td><p>Emitted when the form control&#39;s validity is checked and it doesn&#39;t 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>Button text.</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td><p>Element on the left side of the button.</p>
</td>
  </tr>
  <tr>
    <td>end-icon</td>
    <td><p>Element on the right side of the button.</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>label</td>
    <td><p>Button text.</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td><p>Icon on the left side of the button.</p>
</td>
  </tr>
  <tr>
    <td>end-icon</td>
    <td><p>Icon on the right side of the button.</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 size of the component corner. You can use a specific pixel value, but it&#39;s recommended to reference <a href="/docs/2/styles/design-tokens#shape-corner">design tokens</a>.</p>
</td>
  </tr>
</tbody>
</table>