# Componente Button

Os botões são usados para executar ações, como enviar e-mails, compartilhar documentos ou curtir comentários.

## Como usar {#usage}

Importe o componente quando necessário:

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

Importe o tipo TypeScript do componente quando necessário:

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

Exemplo de uso:

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

## Exemplos {#examples}

### Forma {#example-variant}

Use o atributo `variant` para definir a forma do botão.

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

### Largura total {#example-full-width}

Use o atributo `full-width` para fazer o botão ocupar toda a largura do elemento pai.

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

### Ícone {#example-icon}

Defina os atributos `icon` e `end-icon` para adicionar ícones do Material Icons à esquerda e à direita do botão, respectivamente. Você também pode adicionar elementos pelos slots `icon` e `end-icon`.

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

Defina o atributo `href` para transformar o botão em um link. Assim, você também pode usar os atributos relacionados a links: `download`, `target`, `rel`.

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

### Estado desabilitado e carregando {#example-disabled}

Use o atributo `disabled` para desabilitar o botão; adicione o atributo `loading` para adicionar um estado de carregamento ao botão.

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

## mdui-button API

### Propriedades

<table>
<thead>
  <tr>
    <th>Atributo</th>
    <th>Propriedade</th>
    <th>Reflect</th>
    <th>Tipo</th>
    <th>Padrão</th>
    <th>Descrição</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>Forma do botão. Os valores possíveis são:</p>
<ul>
<li><code>elevated</code>: Botão com sombra, adequado para cenários onde o botão precisa ser visualmente separado do fundo.</li>
<li><code>filled</code>: Efeito visual forte, adequado para ações finais importantes, como &quot;Salvar&quot;, &quot;Confirmar&quot;, etc.</li>
<li><code>tonal</code>: Efeito visual entre <code>filled</code> e <code>outlined</code>, adequado para ações de prioridade média-alta, como &quot;Próximo&quot; em um fluxo.</li>
<li><code>outlined</code>: Botão com borda, adequado para ações de prioridade média e secundárias, como &quot;Voltar&quot;.</li>
<li><code>text</code>: Botão de texto, adequado para ações de prioridade mais baixa.</li>
</ul>
</td>
  </tr>
  <tr>
    <td>full-width</td>
    <td>fullWidth</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Define se o botão deve preencher a largura do elemento pai.</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td>icon</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Nome do ícone Material Icons à esquerda. Também pode ser definido via <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>Nome do ícone Material Icons à direita. Também pode ser definido via <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>A URL de destino do link.</p>
<p>Ao definir esta propriedade, o componente será renderizado internamente como um elemento <code>&lt;a&gt;</code> e poderá usar atributos de link.</p>
</td>
  </tr>
  <tr>
    <td>download</td>
    <td>download</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>O nome do arquivo para download.</p>
<p><strong>Nota</strong>: Esta propriedade só é válida quando o atributo <code>href</code> está definido.</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>Define como o link será aberto. Os valores possíveis são:</p>
<ul>
<li><code>_blank</code>: Abre o link em uma nova janela</li>
<li><code>_parent</code>: Abre o link no frame pai</li>
<li><code>_self</code>: Padrão. Abre o link no frame atual</li>
<li><code>_top</code>: Abre o link na janela inteira</li>
</ul>
<p><strong>Nota</strong>: Esta propriedade só é válida quando o atributo <code>href</code> está definido.</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>A relação entre o documento atual e o documento vinculado. Os valores possíveis são:</p>
<ul>
<li><code>alternate</code>: Versão alternativa do documento atual</li>
<li><code>author</code>: Autor do documento atual ou artigo</li>
<li><code>bookmark</code>: Link permanente para a seção ancestral mais próxima</li>
<li><code>external</code>: O documento referenciado não está no mesmo site do documento atual</li>
<li><code>help</code>: Link para documentação de ajuda relacionada</li>
<li><code>license</code>: O conteúdo principal do documento atual está coberto pela licença de direitos autorais do arquivo referenciado</li>
<li><code>me</code>: O documento atual representa o proprietário do conteúdo vinculado</li>
<li><code>next</code>: O documento atual faz parte de uma série, e o documento referenciado é o próximo da série</li>
<li><code>nofollow</code>: O autor ou editor do documento atual não endossa o arquivo referenciado</li>
<li><code>noreferrer</code>: Não inclui o cabeçalho <code>Referer</code>. Tem efeito semelhante ao <code>noopener</code></li>
<li><code>opener</code>: Se o hiperlink criar um contexto de navegação de nível superior (ou seja, o valor do atributo <code>target</code> for <code>_blank</code>), cria um contexto de navegação auxiliar</li>
<li><code>prev</code>: O documento atual faz parte de uma série, e o documento referenciado é o anterior da série</li>
<li><code>search</code>: Fornece um link para um recurso que pode ser usado para pesquisar o arquivo atual e suas páginas relacionadas</li>
<li><code>tag</code>: Fornece uma tag (identificada pelo endereço fornecido) aplicável ao documento atual</li>
</ul>
<p><strong>Nota</strong>: Disponível apenas quando o atributo <code>href</code> é especificado.</p>
</td>
  </tr>
  <tr>
    <td>autofocus</td>
    <td>autofocus</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Define se o elemento deve receber foco automaticamente após o carregamento da página.</p>
</td>
  </tr>
  <tr>
    <td>tabindex</td>
    <td>tabIndex</td>
    <td>false</td>
    <td>number</td>
    <td></td>
    <td><p>A ordem do elemento ao navegar com a tecla Tab.</p>
</td>
  </tr>
  <tr>
    <td>disabled</td>
    <td>disabled</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Define se o componente está desabilitado.</p>
</td>
  </tr>
  <tr>
    <td>loading</td>
    <td>loading</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Define se o componente está em estado de carregamento.</p>
</td>
  </tr>
  <tr>
    <td>name</td>
    <td>name</td>
    <td>true</td>
    <td>string</td>
    <td>''</td>
    <td><p>O nome do botão, que será enviado com os dados do formulário.</p>
<p><strong>Nota</strong>: Esta propriedade só é válida quando o atributo <code>href</code> não está definido.</p>
</td>
  </tr>
  <tr>
    <td>value</td>
    <td>value</td>
    <td>true</td>
    <td>string</td>
    <td>''</td>
    <td><p>O valor inicial do botão, que será enviado com os dados do formulário.</p>
<p><strong>Nota</strong>: Esta propriedade só é válida quando o atributo <code>href</code> não está definido.</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>O tipo do botão. O tipo padrão é <code>button</code>. Os tipos possíveis são:</p>
<ul>
<li><code>submit</code>: Clicar no botão envia os dados do formulário para o servidor</li>
<li><code>reset</code>: Clicar no botão redefine todos os campos do formulário para seus valores iniciais</li>
<li><code>button</code>: Este tipo de botão não tem comportamento padrão</li>
</ul>
<p><strong>Nota</strong>: Esta propriedade só é válida quando o atributo <code>href</code> não é especificado.</p>
</td>
  </tr>
  <tr>
    <td>form</td>
    <td>form</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>O elemento <code>&lt;form&gt;</code> associado. O valor deste atributo deve ser o <code>id</code> de um elemento <code>&lt;form&gt;</code> na mesma página.</p>
<p>Se este atributo não for especificado, o elemento precisa ser um elemento filho de um <code>&lt;form&gt;</code>. Com este atributo, você pode colocar o elemento em qualquer lugar da página, não apenas como filho do elemento <code>&lt;form&gt;</code>.</p>
<p><strong>Nota</strong>: Esta propriedade só é válida quando o atributo <code>href</code> não é especificado.</p>
</td>
  </tr>
  <tr>
    <td>formaction</td>
    <td>formAction</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Especifica a URL para envio do formulário.</p>
<p>Se este atributo for especificado, ele substituirá o atributo <code>action</code> do elemento <code>&lt;form&gt;</code>.</p>
<p><strong>Nota</strong>: Esta propriedade só é válida quando o atributo <code>href</code> não é especificado e <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>Especifica o tipo de conteúdo ao enviar o formulário para o servidor. Os valores possíveis são:</p>
<ul>
<li><code>application/x-www-form-urlencoded</code>: Valor padrão quando o atributo não é especificado</li>
<li><code>multipart/form-data</code>: Usado quando o formulário contém um elemento <code>&lt;input type=&quot;file&quot;&gt;</code></li>
<li><code>text/plain</code>: Novo no HTML5, usado para depuração</li>
</ul>
<p>Se este atributo for especificado, ele substituirá o atributo <code>enctype</code> do elemento <code>&lt;form&gt;</code>.</p>
<p><strong>Nota</strong>: Esta propriedade só é válida quando o atributo <code>href</code> não é especificado e <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>Especifica o método HTTP a ser usado ao enviar o formulário. Os valores possíveis são:</p>
<ul>
<li><code>post</code>: Os dados do formulário são incluídos no corpo do formulário e enviados ao servidor</li>
<li><code>get</code>: Os dados do formulário são anexados à URI do formulário com <code>?</code> como separador, e a URI resultante é enviada ao servidor. Use este método quando o formulário não tiver efeitos colaterais e contiver apenas caracteres ASCII</li>
</ul>
<p>Se este atributo for definido, ele substituirá o atributo <code>method</code> do elemento <code>&lt;form&gt;</code>.</p>
<p><strong>Nota</strong>: Esta propriedade só é válida quando o atributo <code>href</code> não é definido e <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>Se este atributo for definido, a validação do formulário não será executada ao enviar.</p>
<p>Se este atributo for definido, ele substituirá o atributo <code>novalidate</code> do elemento <code>&lt;form&gt;</code>.</p>
<p><strong>Nota</strong>: Esta propriedade só é válida quando o atributo <code>href</code> não é definido e <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>Onde exibir a resposta recebida após o envio do formulário. Os valores possíveis são:</p>
<ul>
<li><code>_self</code>: Opção padrão, abre no frame atual</li>
<li><code>_blank</code>: Abre em uma nova janela</li>
<li><code>_parent</code>: Abre no frame pai</li>
<li><code>_top</code>: Abre na janela inteira</li>
</ul>
<p>Se este atributo for definido, ele substituirá o atributo <code>target</code> do elemento <code>&lt;form&gt;</code>.</p>
<p><strong>Nota</strong>: Esta propriedade só é válida quando o atributo <code>href</code> não é definido e <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>Objeto que representa o estado de validação do formulário. Consulte <a href="https://developer.mozilla.org/pt-BR/docs/Web/API/ValidityState" target="_blank" rel="noopener nofollow"><code>ValidityState</code></a> para mais detalhes.</p>
</td>
  </tr>
  <tr>
    <td>undefined</td>
    <td>validationMessage</td>
    <td>false</td>
    <td>string</td>
    <td></td>
    <td><p>Se a validação do formulário falhar, esta propriedade conterá uma mensagem de erro. Se a validação for bem-sucedida, esta propriedade será uma string vazia.</p>
</td>
  </tr>
</tbody>
</table>

### Métodos

<table>
<thead>
  <tr>
    <th>Nome</th>
    <th>Descrição</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>click(): void</td>
    <td><p>Simula um clique do mouse no elemento.</p>
</td>
  </tr>
  <tr>
    <td>focus(options?: FocusOptions): void</td>
    <td><p>Define o foco no elemento atual.</p>
<p>Você pode passar um objeto como argumento, com as seguintes propriedades:</p>
<ul>
<li><code>preventScroll</code>: Por padrão, após o elemento receber o foco, a página é rolada para que ele fique visível. Se você não quiser que a página role, defina esta propriedade como <code>true</code>.</li>
</ul>
</td>
  </tr>
  <tr>
    <td>blur(): void</td>
    <td><p>Remove o foco do elemento atual.</p>
</td>
  </tr>
  <tr>
    <td>checkValidity(): boolean</td>
    <td><p>Verifica se o campo do formulário passou na validação. Se não passou, retorna <code>false</code> e dispara o evento <code>invalid</code>; se passou, retorna <code>true</code>.</p>
</td>
  </tr>
  <tr>
    <td>reportValidity(): boolean</td>
    <td><p>Verifica se o campo do formulário passou na validação. Se não passou, retorna <code>false</code> e dispara o evento <code>invalid</code>; se passou, retorna <code>true</code>.</p>
<p>Se a validação falhar, também exibe uma mensagem de erro no componente.</p>
</td>
  </tr>
  <tr>
    <td>setCustomValidity(message: string): void</td>
    <td><p>Define um texto de erro personalizado. Enquanto este texto não estiver vazio, indica que o campo não passou na validação.</p>
</td>
  </tr>
</tbody>
</table>

### Eventos

<table>
<thead>
  <tr>
    <th>Nome</th>
    <th>Descrição</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>focus</td>
    <td><p>Disparado ao receber foco.</p>
</td>
  </tr>
  <tr>
    <td>blur</td>
    <td><p>Disparado ao perder o foco.</p>
</td>
  </tr>
  <tr>
    <td>invalid</td>
    <td><p>Disparado quando a validação do campo do formulário falha.</p>
</td>
  </tr>
</tbody>
</table>

### Slots

<table>
<thead>
  <tr>
    <th>Nome</th>
    <th>Descrição</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>(padrão)</td>
    <td><p>Texto do botão.</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td><p>Elemento à esquerda do botão.</p>
</td>
  </tr>
  <tr>
    <td>end-icon</td>
    <td><p>Elemento à direita do botão.</p>
</td>
  </tr>
</tbody>
</table>

### CSS Parts

<table>
<thead>
  <tr>
    <th>Nome</th>
    <th>Descrição</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>button</td>
    <td><p>Elemento <code>&lt;button&gt;</code> ou <code>&lt;a&gt;</code> interno.</p>
</td>
  </tr>
  <tr>
    <td>label</td>
    <td><p>Texto do botão.</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td><p>Ícone à esquerda do botão.</p>
</td>
  </tr>
  <tr>
    <td>end-icon</td>
    <td><p>Ícone à direita do botão.</p>
</td>
  </tr>
  <tr>
    <td>loading</td>
    <td><p>Elemento <code>&lt;mdui-circular-progress&gt;</code> no estado de carregamento.</p>
</td>
  </tr>
</tbody>
</table>

### Propriedades CSS personalizadas

<table>
<thead>
  <tr>
    <th>Nome</th>
    <th>Descrição</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>--shape-corner</td>
    <td><p>Tamanho da borda arredondada do componente. Pode ser um valor em pixels, mas é recomendado usar os <a href="/pt-br/docs/2/styles/design-tokens#shape-corner">design tokens</a>.</p>
</td>
  </tr>
</tbody>
</table>