# Floating Action Button Component

The Floating Action Button (FAB) is a primary action button that gives users quick access to key actions.

## Usage {#usage}

Import the component:

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

Import the TypeScript type:

```ts
import type { Fab } from 'mdui/components/fab.js';
```

Example:

```html
<mdui-fab icon="edit"></mdui-fab>
```

## Examples {#examples}

### Icon {#example-icon}

Use the `icon` attribute to set the Material Icon name, or use the `icon` slot.

```html
<mdui-fab icon="edit"></mdui-fab>
<mdui-fab>
  <mdui-icon slot="icon" name="edit"></mdui-icon>
</mdui-fab>
```

### Extended State {#example-extended}

Use `extended` to show the default slot's text in the extended state.

```html
<mdui-fab extended icon="edit">Compose</mdui-fab>
```

### Shape {#example-variant}

Use the `variant` attribute to set the FAB shape.

```html
<mdui-fab variant="primary" icon="edit"></mdui-fab>
<mdui-fab variant="surface" icon="edit"></mdui-fab>
<mdui-fab variant="secondary" icon="edit"></mdui-fab>
<mdui-fab variant="tertiary" icon="edit"></mdui-fab>
```

### Size {#example-size}

Use the `size` attribute to set the FAB size.

```html
<mdui-fab size="small" icon="edit"></mdui-fab>
<mdui-fab size="normal" icon="edit"></mdui-fab>
<mdui-fab size="large" icon="edit"></mdui-fab>
```

### Link {#example-link}

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

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

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

Use `disabled` to disable the FAB. Use `loading` to show a loading state.

```html
<mdui-fab disabled icon="edit"></mdui-fab>
<mdui-fab loading icon="edit"></mdui-fab>
<mdui-fab loading disabled icon="edit"></mdui-fab>
```

## mdui-fab 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;primary&#39; | &#39;surface&#39; | &#39;secondary&#39; | &#39;tertiary&#39;</td>
    <td>'primary'</td>
    <td><p>Sets the FAB color. Possible values:</p>
<ul>
<li><code>primary</code>: Uses the primary container background color.</li>
<li><code>surface</code>: Uses the surface container high background color.</li>
<li><code>secondary</code>: Uses the secondary container background color.</li>
<li><code>tertiary</code>: Uses the tertiary container background color.</li>
</ul>
</td>
  </tr>
  <tr>
    <td>size</td>
    <td>size</td>
    <td>true</td>
    <td>&#39;normal&#39; | &#39;small&#39; | &#39;large&#39;</td>
    <td>'normal'</td>
    <td><p>Sets the FAB size. Possible values:</p>
<ul>
<li><code>normal</code>: Normal size.</li>
<li><code>small</code>: Small size.</li>
<li><code>large</code>: Large size.</li>
</ul>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td>icon</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Sets the Material Icons name. Alternatively, use <code>slot=&quot;icon&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>extended</td>
    <td>extended</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Extends the FAB to show text alongside the icon.</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 FAB gains focus.</p>
</td>
  </tr>
  <tr>
    <td>blur</td>
    <td><p>Emitted when the FAB loses focus.</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>Text content.</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td><p>Icon.</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>Text on the right side.</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td><p>Icon on the left side.</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-small</td>
    <td><p>The corner radius of the component when <code>size=&quot;small&quot;</code>. 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>
  <tr>
    <td>--shape-corner-normal</td>
    <td><p>The corner radius of the component when <code>size=&quot;normal&quot;</code>. 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>
  <tr>
    <td>--shape-corner-large</td>
    <td><p>The corner radius of the component when <code>size=&quot;large&quot;</code>. 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>