# Componente Botón

El componente Botón se usa para ejecutar acciones, como enviar un correo, compartir un documento o marcar un comentario con un me gusta.

## Uso {#usage}

Importa el componente cuando lo necesites:

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

Importa el tipo TypeScript cuando lo necesites:

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

Uso:

```html
<mdui-button>Botón</mdui-button>
```

## Ejemplos {#examples}

### Forma {#example-variant}

El atributo `variant` define la forma del botón.

```html
<mdui-button variant="elevated">Elevado</mdui-button>
<mdui-button variant="filled">Relleno</mdui-button>
<mdui-button variant="tonal">Tonal</mdui-button>
<mdui-button variant="outlined">Con contorno</mdui-button>
<mdui-button variant="text">Texto</mdui-button>
```

### Ancho completo {#example-full-width}

El atributo `full-width` hace que el botón ocupe todo el ancho del elemento padre.

```html
<mdui-button full-width>Botón</mdui-button>
```

### Icono {#example-icon}

Los atributos `icon` y `end-icon` permiten añadir iconos de Material Icons a la izquierda y derecha del botón respectivamente. También puedes añadir elementos a la izquierda y derecha del botón mediante los slots `icon` y `end-icon`.

```html
<mdui-button icon="search" end-icon="arrow_forward">Icono</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>
```

### Enlace {#example-link}

Con el atributo `href`, el botón actúa como enlace; también puedes usar `download`, `target` y `rel`.

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

### Estados deshabilitado y de carga {#example-disabled}

El atributo `disabled` deshabilita el botón; añade el atributo `loading` para añadir un estado de carga al botón.

```html
<mdui-button disabled>Deshabilitado</mdui-button>
<mdui-button loading>Cargando</mdui-button>
<mdui-button loading disabled>Cargando y deshabilitado</mdui-button>
```

## mdui-button API

### Propiedades

<table>
<thead>
  <tr>
    <th>Atributo</th>
    <th>Propiedad</th>
    <th>Reflect</th>
    <th>Tipo</th>
    <th>Predeterminado</th>
    <th>Descripción</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>Variante del botón. Los valores posibles son:</p>
<ul>
<li><code>elevated</code>: Botón con sombra, adecuado para situaciones en las que se necesita separar visualmente el botón del fondo</li>
<li><code>filled</code>: Efecto visual intenso, adecuado para acciones finales en procesos importantes, como &quot;Guardar&quot;, &quot;Confirmar&quot;, etc.</li>
<li><code>tonal</code>: Efecto visual entre <code>filled</code> y <code>outlined</code>, adecuado para acciones de prioridad media-alta, como &quot;Siguiente&quot; en un flujo</li>
<li><code>outlined</code>: Botón con borde, adecuado para acciones de prioridad media y secundarias, como &quot;Volver&quot;</li>
<li><code>text</code>: Botón de texto, adecuado para acciones de prioridad más baja</li>
</ul>
</td>
  </tr>
  <tr>
    <td>full-width</td>
    <td>fullWidth</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Indica si debe ocupar todo el ancho del elemento padre.</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td>icon</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Nombre del icono de Material Icons a la izquierda. También se puede establecer mediante <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>Nombre del icono de Material Icons a la derecha. También se puede establecer mediante <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>URL de destino del enlace.</p>
<p>Si se define esta propiedad, el componente se representará como un elemento <code>&lt;a&gt;</code> y podrá usar las propiedades de enlace.</p>
</td>
  </tr>
  <tr>
    <td>download</td>
    <td>download</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Nombre del archivo para el enlace de descarga.</p>
<p><strong>Nota</strong>: Esta propiedad solo tiene efecto si se ha definido la propiedad <code>href</code>.</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>Especifica dónde abrir el enlace. Los valores posibles son:</p>
<ul>
<li><code>_blank</code>: Abrir el enlace en una nueva ventana</li>
<li><code>_parent</code>: Abrir el enlace en el marco principal</li>
<li><code>_self</code>: Predeterminado. Abrir el enlace en el marco actual</li>
<li><code>_top</code>: Abrir el enlace en la ventana completa</li>
</ul>
<p><strong>Nota</strong>: Esta propiedad solo tiene efecto si se ha definido la propiedad <code>href</code>.</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>Relación entre el documento actual y el documento enlazado. Los valores posibles son:</p>
<ul>
<li><code>alternate</code>: Versión alternativa del documento actual</li>
<li><code>author</code>: Autor del documento o artículo actual</li>
<li><code>bookmark</code>: Enlace permanente a la sección contenedora más cercana</li>
<li><code>external</code>: El documento referenciado no está en el mismo sitio que el documento actual</li>
<li><code>help</code>: Enlace a la documentación de ayuda relacionada</li>
<li><code>license</code>: El contenido principal del documento actual está cubierto por la licencia de derechos de autor del documento referenciado</li>
<li><code>me</code>: El documento actual representa al propietario del contenido enlazado</li>
<li><code>next</code>: El documento actual es parte de una serie y el documento referenciado es el siguiente de la serie</li>
<li><code>nofollow</code>: El autor o editor del documento actual no respalda el documento referenciado</li>
<li><code>noreferrer</code>: No incluye el encabezado <code>Referer</code>. Similar al efecto de <code>noopener</code></li>
<li><code>opener</code>: Si el hipervínculo crea un contexto de navegación de nivel superior (es decir, el valor del atributo <code>target</code> es <code>_blank</code>), crea un contexto de navegación auxiliar</li>
<li><code>prev</code>: El documento actual es parte de una serie y el documento referenciado es el anterior de la serie</li>
<li><code>search</code>: Proporciona un enlace a un recurso que se puede utilizar para buscar el archivo actual y sus páginas relacionadas</li>
<li><code>tag</code>: Proporciona una etiqueta adecuada para el documento actual (identificada por la dirección dada)</li>
</ul>
<p><strong>Nota</strong>: Disponible solo cuando se especifica el atributo <code>href</code>.</p>
</td>
  </tr>
  <tr>
    <td>autofocus</td>
    <td>autofocus</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Indica si el componente debe recibir el foco automáticamente cuando la página termine de cargar.</p>
</td>
  </tr>
  <tr>
    <td>tabindex</td>
    <td>tabIndex</td>
    <td>false</td>
    <td>number</td>
    <td></td>
    <td><p>Orden del elemento al navegar con la tecla Tab.</p>
</td>
  </tr>
  <tr>
    <td>disabled</td>
    <td>disabled</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Indica si está deshabilitado.</p>
</td>
  </tr>
  <tr>
    <td>loading</td>
    <td>loading</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Indica si está en estado de carga.</p>
</td>
  </tr>
  <tr>
    <td>name</td>
    <td>name</td>
    <td>true</td>
    <td>string</td>
    <td>''</td>
    <td><p>Nombre del botón que se enviará con los datos del formulario.</p>
<p><strong>Nota</strong>: Esta propiedad solo tiene efecto si no se ha definido la propiedad <code>href</code>.</p>
</td>
  </tr>
  <tr>
    <td>value</td>
    <td>value</td>
    <td>true</td>
    <td>string</td>
    <td>''</td>
    <td><p>Valor inicial del botón que se enviará con los datos del formulario.</p>
<p><strong>Nota</strong>: Esta propiedad solo tiene efecto si no se ha definido la propiedad <code>href</code>.</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>Tipo del botón. El tipo predeterminado es <code>button</code>. Los tipos posibles son:</p>
<ul>
<li><code>submit</code>: Al hacer clic en el botón, se enviarán los datos del formulario al servidor</li>
<li><code>reset</code>: Al hacer clic en el botón, se restablecerán todos los campos del formulario a sus valores iniciales</li>
<li><code>button</code>: Este tipo de botón no tiene comportamiento predeterminado</li>
</ul>
<p><strong>Nota</strong>: Esta propiedad solo tiene efecto si no se ha especificado la propiedad <code>href</code>.</p>
</td>
  </tr>
  <tr>
    <td>form</td>
    <td>form</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Elemento <code>&lt;form&gt;</code> asociado. El valor de esta propiedad debe ser el <code>id</code> de un elemento <code>&lt;form&gt;</code> en la misma página.</p>
<p>Si no se especifica esta propiedad, el elemento debe ser hijo de un elemento <code>&lt;form&gt;</code>. Con esta propiedad, puedes colocar el elemento en cualquier lugar de la página, no solo como hijo de un elemento <code>&lt;form&gt;</code>.</p>
<p><strong>Nota</strong>: Esta propiedad solo tiene efecto si no se ha especificado la propiedad <code>href</code>.</p>
</td>
  </tr>
  <tr>
    <td>formaction</td>
    <td>formAction</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Especifica la URL a la que se enviará el formulario.</p>
<p>Si se especifica esta propiedad, anulará el atributo <code>action</code> del elemento <code>&lt;form&gt;</code>.</p>
<p><strong>Nota</strong>: Esta propiedad solo tiene efecto si no se ha especificado la propiedad <code>href</code> y <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 el tipo de contenido al enviar el formulario al servidor. Los valores posibles son:</p>
<ul>
<li><code>application/x-www-form-urlencoded</code>: Valor predeterminado cuando no se especifica este atributo</li>
<li><code>multipart/form-data</code>: Se usa cuando el formulario contiene un elemento <code>&lt;input type=&quot;file&quot;&gt;</code></li>
<li><code>text/plain</code>: Nuevo en HTML5, para depuración</li>
</ul>
<p>Si se especifica esta propiedad, anulará el atributo <code>enctype</code> del elemento <code>&lt;form&gt;</code>.</p>
<p><strong>Nota</strong>: Esta propiedad solo tiene efecto si no se ha especificado la propiedad <code>href</code> y <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 el método HTTP utilizado al enviar el formulario. Los valores posibles son:</p>
<ul>
<li><code>post</code>: Los datos del formulario se incluyen en el cuerpo de la solicitud y se envían al servidor</li>
<li><code>get</code>: Los datos del formulario se adjuntan al URI del formulario con <code>?</code> como separador, y el URI generado se envía al servidor. Se utiliza este método cuando el formulario no tiene efectos secundarios y solo contiene caracteres ASCII</li>
</ul>
<p>Si se define esta propiedad, anulará el atributo <code>method</code> del elemento <code>&lt;form&gt;</code>.</p>
<p><strong>Nota</strong>: Esta propiedad solo tiene efecto si no se ha definido la propiedad <code>href</code> y <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>Si se define esta propiedad, no se realizará la validación del formulario al enviarlo.</p>
<p>Si se define esta propiedad, anulará el atributo <code>novalidate</code> del elemento <code>&lt;form&gt;</code>.</p>
<p><strong>Nota</strong>: Esta propiedad solo tiene efecto si no se ha definido la propiedad <code>href</code> y <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>Dónde mostrar la respuesta recibida después de enviar el formulario. Los valores posibles son:</p>
<ul>
<li><code>_self</code>: Opción predeterminada, abrir en el marco actual</li>
<li><code>_blank</code>: Abrir en una nueva ventana</li>
<li><code>_parent</code>: Abrir en el marco principal</li>
<li><code>_top</code>: Abrir en la ventana completa</li>
</ul>
<p>Si se define esta propiedad, anulará el atributo <code>target</code> del elemento <code>&lt;form&gt;</code>.</p>
<p><strong>Nota</strong>: Esta propiedad solo tiene efecto si no se ha definido la propiedad <code>href</code> y <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 de estado de validación del formulario, véase <a href="https://developer.mozilla.org/en-US/docs/Web/API/ValidityState" target="_blank" rel="noopener nofollow"><code>ValidityState</code></a>.</p>
</td>
  </tr>
  <tr>
    <td>undefined</td>
    <td>validationMessage</td>
    <td>false</td>
    <td>string</td>
    <td></td>
    <td><p>Si falla la validación del formulario, esta propiedad contendrá un mensaje informativo. Si la validación es correcta, esta propiedad será una cadena vacía.</p>
</td>
  </tr>
</tbody>
</table>

### Métodos

<table>
<thead>
  <tr>
    <th>Nombre</th>
    <th>Descripción</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>click(): void</td>
    <td><p>Simula un clic del ratón en el elemento.</p>
</td>
  </tr>
  <tr>
    <td>focus(options?: FocusOptions): void</td>
    <td><p>Establece el foco en el elemento actual.</p>
<p>Puede pasarse un objeto como parámetro con las siguientes propiedades:</p>
<ul>
<li><code>preventScroll</code>: Por defecto, cuando el elemento recibe el foco, la página se desplaza hasta mostrarlo. Si no quiere que la página se desplace, defina esta propiedad como <code>true</code>.</li>
</ul>
</td>
  </tr>
  <tr>
    <td>blur(): void</td>
    <td><p>Quita el foco del elemento actual.</p>
</td>
  </tr>
  <tr>
    <td>checkValidity(): boolean</td>
    <td><p>Comprueba si el campo del formulario pasa la validación. Si falla, devuelve <code>false</code> y dispara el evento <code>invalid</code>; si la pasa, devuelve <code>true</code>.</p>
</td>
  </tr>
  <tr>
    <td>reportValidity(): boolean</td>
    <td><p>Comprueba si el campo del formulario pasa la validación. Si falla, devuelve <code>false</code> y dispara el evento <code>invalid</code>; si la pasa, devuelve <code>true</code>.</p>
<p>Si la validación falla, también muestra un mensaje de error en el componente.</p>
</td>
  </tr>
  <tr>
    <td>setCustomValidity(message: string): void</td>
    <td><p>Establece un mensaje de error personalizado. Si este mensaje no está vacío, indica que el campo no ha pasado la validación.</p>
</td>
  </tr>
</tbody>
</table>

### Eventos

<table>
<thead>
  <tr>
    <th>Nombre</th>
    <th>Descripción</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>focus</td>
    <td><p>Se dispara cuando recibe el foco.</p>
</td>
  </tr>
  <tr>
    <td>blur</td>
    <td><p>Se dispara cuando pierde el foco.</p>
</td>
  </tr>
  <tr>
    <td>invalid</td>
    <td><p>Se dispara cuando falla la validación del campo del formulario.</p>
</td>
  </tr>
</tbody>
</table>

### Slots

<table>
<thead>
  <tr>
    <th>Nombre</th>
    <th>Descripción</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>(predeterminado)</td>
    <td><p>Texto del botón.</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td><p>Elemento a la izquierda del botón.</p>
</td>
  </tr>
  <tr>
    <td>end-icon</td>
    <td><p>Elemento a la derecha del botón.</p>
</td>
  </tr>
</tbody>
</table>

### CSS Parts

<table>
<thead>
  <tr>
    <th>Nombre</th>
    <th>Descripción</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>button</td>
    <td><p>Elemento interno <code>&lt;button&gt;</code> o <code>&lt;a&gt;</code>.</p>
</td>
  </tr>
  <tr>
    <td>label</td>
    <td><p>Texto del botón.</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td><p>Icono a la izquierda del botón.</p>
</td>
  </tr>
  <tr>
    <td>end-icon</td>
    <td><p>Icono a la derecha del botón.</p>
</td>
  </tr>
  <tr>
    <td>loading</td>
    <td><p>Elemento <code>&lt;mdui-circular-progress&gt;</code> en estado de carga.</p>
</td>
  </tr>
</tbody>
</table>

### CSS Custom Properties

<table>
<thead>
  <tr>
    <th>Nombre</th>
    <th>Descripción</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>--shape-corner</td>
    <td><p>Tamaño de la esquina redondeada del componente. Se puede especificar un valor de píxel concreto; pero se recomienda hacer referencia a <a href="/es/docs/2/styles/design-tokens#shape-corner">design tokens</a>.</p>
</td>
  </tr>
</tbody>
</table>