`. A documentação de cada componente descreve detalhadamente sua API completa, incluindo atributos, métodos, eventos, slots, CSS Part, propriedades CSS personalizadas, etc. Este capítulo da documentação apresentará como usar os Web Components. ## Atributo {#attribute} Os atributos são divididos em atributos HTML e propriedades JavaScript. Eles geralmente são mapeados um a um e permanecem sincronizados. Ou seja, quando você atualiza o valor de um atributo HTML, o valor da propriedade JavaScript também é atualizado; e vice-versa. Os atributos HTML podem ser definidos diretamente na string HTML do componente e lidos/modificados pelos métodos `getAttribute` e `setAttribute`: ```html Clique em mim ``` As propriedades JavaScript podem ser lidas ou definidas diretamente no valor da propriedade da instância do componente: ```html Clique em mim ``` Algumas propriedades têm valor booleano. Quando o atributo HTML correspondente existe, a propriedade JavaScript é `true`; caso contrário, é `false`. No entanto, para compatibilidade com certos frameworks, o mdui também trata o valor string `'false'` como o valor booleano `false`. ```html

``` Às vezes, o valor da propriedade é um array, objeto ou função. Nesses casos, existe apenas a propriedade JavaScript, sem o atributo HTML correspondente. Por exemplo, a propriedade [`labelFormatter`](/pt-br/docs/2/components/slider#attributes-labelFormatter) do componente [``](/pt-br/docs/2/components/slider) é uma função. Você só pode definir essa propriedade via JavaScript: ```html ``` Abaixo, usando parte da documentação de propriedades do componente [``](/pt-br/docs/2/components/slider) como exemplo: | Atributo HTML | Propriedade JavaScript | reflect | | ------------- | ---------------------- | -------------------------------------------------------------------------------------- | | `name` | `name` | | | `value` | `value` | | | | `labelFormatter` | | Este componente tem atributo HTML e propriedade JavaScript para `name`, e a coluna reflect indica que atualizar a propriedade JavaScript também atualiza o atributo HTML. Para `value`, atualizar a propriedade JavaScript não atualiza o atributo HTML. A propriedade `labelFormatter` existe apenas como propriedade JavaScript. ## Método {#method} Alguns componentes fornecem métodos públicos que você pode chamar para diferentes funcionalidades. Por exemplo, o método [`focus()`](/pt-br/docs/2/components/text-field#methods-focus) do componente [``](/pt-br/docs/2/components/text-field) faz o campo de texto ganhar foco. ```html ``` Consulte a página de documentação de cada componente para ver todos os métodos disponíveis e seus parâmetros. ## Evento {#event} Alguns componentes acionam eventos ao executar ações específicas. Por exemplo, o componente [``](/pt-br/docs/2/components/dialog) aciona o evento [`open`](/pt-br/docs/2/components/dialog#events-open) ao abrir. Você pode monitorar este evento para executar ações personalizadas. ```html Diálogo ``` Consulte a página de documentação de cada componente para ver todos os eventos disponíveis e seus parâmetros. Se você estiver usando o mdui em outros frameworks (como Vue, React, Angular, etc.), pode usar a sintaxe fornecida pelo framework para vincular eventos. No entanto, alguns frameworks (como React) só permitem vincular eventos padrão (como o evento `click`) com sua sintaxe de vinculação de eventos, não eventos personalizados (como o evento `open`). Portanto, ao vincular eventos personalizados no React, você precisa primeiro obter uma referência ao elemento e usar o método `addEventListener` para vincular o evento. Para mais informações sobre como usar o mdui no React, consulte [Integração com frameworks - React](/pt-br/docs/2/frameworks/react). ## Slot {#slot} Muitos componentes fornecem slots para inserir conteúdo HTML personalizado dentro do componente. O mais comum é o slot padrão, que é um fragmento HTML ou texto simples dentro do componente. Por exemplo, o slot padrão do componente [``](/pt-br/docs/2/components/button) define o texto do botão. No exemplo, "Clique em mim" é o conteúdo do slot padrão: ```html Clique em mim ``` Alguns componentes também fornecem slots nomeados. Para slots nomeados, você precisa especificar o nome do slot no atributo HTML `slot`. No exemplo a seguir, o componente [``](/pt-br/docs/2/components/icon) especifica `slot="start"`, indicando que é um slot nomeado chamado [`start`](/pt-br/docs/2/components/button#slots-icon). Isso significa que este ícone será inserido no lado esquerdo do componente: ```html Configurações ``` Se um componente usa vários slots nomeados, a ordem entre eles não é importante. Contanto que estejam dentro do componente, o navegador os colocará automaticamente nas posições corretas. Consulte a página de documentação de cada componente para ver todos os slots suportados. ## Propriedade CSS personalizada {#css-custom-properties} Propriedades CSS personalizadas são variáveis em CSS. O mdui define uma série de [propriedades CSS personalizadas globais](/pt-br/docs/2/styles/design-tokens) que são referenciadas internamente por cada componente. Portanto, modificando essas propriedades CSS personalizadas, você pode alterar globalmente a aparência dos componentes do mdui. Por exemplo, o código a seguir reduz o tamanho dos cantos arredondados de todos os componentes: ```css :root { --mdui-shape-corner-extra-small: 0.125rem; --mdui-shape-corner-small: 0.25rem; --mdui-shape-corner-medium: 0.375rem; --mdui-shape-corner-large: 0.5rem; --mdui-shape-corner-extra-large: 0.875rem; } ``` Você também pode modificar as propriedades CSS personalizadas em um escopo local. Por exemplo, o código a seguir reduz o tamanho dos cantos arredondados apenas no elemento com `class="sharp"` e seus elementos filhos: ```css .sharp { --mdui-shape-corner-extra-small: 0.125rem; --mdui-shape-corner-small: 0.25rem; --mdui-shape-corner-medium: 0.375rem; --mdui-shape-corner-large: 0.5rem; --mdui-shape-corner-extra-large: 0.875rem; } ``` Alguns componentes também fornecem propriedades CSS personalizadas específicas do componente. O escopo dessas propriedades é o componente específico, portanto não incluem o prefixo `--mdui`. Por exemplo, o código a seguir modifica a propriedade `z-index` do componente [``](/pt-br/docs/2/components/dialog) alterando sua propriedade personalizada `--z-index`: ```css mdui-dialog { --z-index: 3000; } ``` Consulte a página de documentação de cada componente para ver as propriedades CSS personalizadas suportadas pelo componente. ## CSS Part {#css-part} Os componentes mdui usam shadow DOM para encapsular estilos e comportamentos, mas seletores CSS convencionais não conseguem selecionar elementos dentro do shadow DOM. Portanto, alguns componentes adicionam o atributo `part` a elementos do shadow DOM. Você pode usar o seletor CSS `::part` para selecionar os elementos correspondentes e sobrescrever parte de seus estilos. Por exemplo, o código a seguir usa a part [`button`](/pt-br/docs/2/components/button#cssParts-button) para modificar o preenchimento interno do botão, e as parts [`label`](/pt-br/docs/2/components/button#cssParts-label), [`icon`](/pt-br/docs/2/components/button#cssParts-icon), [`end-icon`](/pt-br/docs/2/components/button#cssParts-end-icon) para modificar as cores do texto e dos ícones esquerdo/direito: ```html Botão ``` Para ver a estrutura e os estilos padrão dos elementos shadow DOM do componente, você pode abrir as ferramentas de desenvolvimento do seu navegador. Antes de usar CSS Part, você deve avaliar se as propriedades CSS personalizadas globais e as propriedades CSS personalizadas específicas do componente atendem às suas necessidades. Se atenderem, priorize o uso de propriedades CSS personalizadas para personalizar os estilos. Consulte a página de documentação de cada componente para ver todas as partes `part` expostas pelo componente. ## Mecanismo de atualização do componente {#update-mechanism} Os componentes mdui são baseados no [Lit](https://lit.dev/). Lit é uma biblioteca leve que torna o desenvolvimento de Web Components mais simples. Ao usar componentes mdui, você pode precisar entender seu mecanismo de renderização e atualização. Quando você modifica uma propriedade de um componente mdui, o componente é re-renderizado. No entanto, esse processo de re-renderização não é síncrono. Quando você modifica várias propriedades ao mesmo tempo, o Lit armazena em cache essas alterações até o próximo ciclo de atualização, garantindo que cada componente seja re-renderizado apenas uma vez, independentemente de quantas vezes você modificar as propriedades. Além disso, apenas as partes do shadow DOM que sofreram alterações são re-renderizadas. No exemplo a seguir, definimos a propriedade JavaScript `disabled` do botão como `true` e imediatamente consultamos seu atributo HTML. No entanto, como o componente ainda não foi re-renderizado, o atributo HTML consultado ainda é `false`: ```js const button = document.querySelector('mdui-button'); button.disabled = true; console.log(button.hasAttribute('disabled')); // false ``` Para aguardar a conclusão da re-renderização após uma alteração de propriedade, use a propriedade `updateComplete` do componente. Esta propriedade retorna uma Promise que será resolvida quando a re-renderização do componente for concluída: ```js const button = document.querySelector('mdui-button'); button.disabled = true; button.updateComplete.then(() => { console.log(button.hasAttribute('disabled')); // true }); ``` # Suporte a TypeScript O mdui é desenvolvido em TypeScript, portanto, oferece bom suporte ao TypeScript. Todas as bibliotecas oficiais do mdui vêm com arquivos de declaração de tipos e podem ser usadas diretamente. ## Tipo de instância do componente {#instance} Às vezes, você pode precisar afirmar que uma variável JavaScript é uma instância de componente do mdui. Assim, você pode importar diretamente o tipo de componente correspondente do mdui. Por exemplo, importar o tipo do componente Tooltip do arquivo do componente: ```ts import type { Tooltip } from 'mdui/components/tooltip.js'; ``` Ou importar o tipo do componente Tooltip diretamente do mdui: ```ts import type { Tooltip } from 'mdui'; ``` Em seguida, você pode afirmar que uma variável JavaScript é do tipo Tooltip: ```ts const tooltip = document.querySelector('mdui-tooltip') as Tooltip; ``` Neste ponto, seu IDE automaticamente fornecerá dicas sobre as propriedades e métodos da variável `tooltip`. Se você adicionar um ouvinte de evento na variável `tooltip`, também será automaticamente sugerido o nome do evento, o tipo do evento e o apontamento de `this` na função de retorno: ```ts tooltip.addEventListener('open', function (event) {}); ``` ## Tipo de evento {#event} Cada componente exporta uma interface que mapeia os nomes de eventos do componente e seus respectivos tipos de objeto de evento. O nome da interface é `${nomeComponente}EventMap`. Por exemplo, o componente Tooltip exporta uma interface chamada `TooltipEventMap`: ```ts export interface TooltipEventMap { open: CustomEvent; opened: CustomEvent; close: CustomEvent; closed: CustomEvent; } ``` Você pode importar esta interface do arquivo do componente: ```ts import type { TooltipEventMap } from 'mdui/components/tooltip.js'; ``` Ou importá-la diretamente do mdui: ```ts import type { TooltipEventMap } from 'mdui'; ``` Observe que esta interface contém apenas eventos específicos do componente. No entanto, os componentes do mdui herdam de `HTMLElement`, portanto, também suportam eventos de `HTMLElement`. Você pode usar um tipo de interseção para obter todos os tipos de eventos do componente: ```ts type TooltipAndHTMLElementEventMap = TooltipEventMap & HTMLElementEventMap; ``` # Suporte a IDE mdui é otimizado especificamente para VS Code e WebStorm, fornecendo recursos como autocompletar código, dicas ao passar o mouse, etc., nessas IDEs. ## VS Code {#vscode} ### mdui instalado via npm {#vscode-npm} Se você instalou o mdui via npm, siga as etapas abaixo para ativar o suporte a IDE do VS Code no projeto atual: 1. Crie o diretório `.vscode` na raiz do projeto. 2. Crie o arquivo `settings.json` no diretório `.vscode`. 3. Adicione o seguinte código ao arquivo `settings.json`: ```json { "html.customData": ["./node_modules/mdui/html-data.en.json"], "css.customData": ["./node_modules/mdui/css-data.en.json"] } ``` Se o arquivo `settings.json` já existir, basta adicionar as duas linhas de código acima ao nó raiz do documento JSON. Após a modificação, reinicie o VS Code. ### mdui usado via CDN {#vscode-cdn} Se você está usando mdui via CDN, pode obter suporte a IDE instalando a extensão do mdui para VS Code. Procure por `mdui` na loja de extensões do VS Code e selecione o primeiro resultado para instalar, ou [clique aqui para instalar](vscode:extension/zdhxiong.mdui). Após a instalação, todos os projetos terão suporte a IDE do mdui. Recomenda-se instalar via npm e configurar o arquivo `settings.json` em vez de instalar a extensão do VS Code, para garantir que o suporte a IDE esteja alinhado com a versão do mdui em uso. ## WebStorm {#webstorm} ### mdui instalado via npm {#webstorm-npm} Se você instalou o mdui via npm, siga as etapas abaixo para ativar o suporte a IDE do WebStorm no projeto atual: 1. Adicione o seguinte código ao nó raiz do arquivo `package.json` na raiz do projeto: ```json { "web-types": ["./node_modules/mdui/web-types.en.json"] } ``` Se o nó raiz do arquivo `package.json` já tiver a propriedade `web-types`, basta adicionar `./node_modules/mdui/web-types.en.json` ao array `web-types`. Após a modificação, reinicie o WebStorm. ### mdui usado via CDN {#webstorm-cdn} Se você está usando mdui via CDN, pode obter suporte a IDE instalando o plugin do mdui para WebStorm. Procure por `mdui` na loja de plugins do WebStorm e selecione o primeiro resultado para instalar. Após a instalação, todos os projetos terão suporte a IDE do mdui. Recomenda-se instalar via npm para obter suporte a IDE em vez de instalar o plugin do WebStorm, para garantir que o suporte a IDE esteja alinhado com a versão do mdui em uso. ## Diferenças de suporte entre VS Code e WebStorm {#difference} O suporte do mdui para VS Code e WebStorm tem algumas diferenças. A tabela abaixo lista as diferenças detalhadas: | Local com autocompletar e dicas ao passar o mouse | VS Code | WebStorm | | ----------------------------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Nome da tag HTML | | | | Nome do atributo na tag HTML | | | | Valores enumerados de atributos na tag HTML | | (não suporta exibição de comentários nos valores enumerados) | | Nome do evento na tag HTML | | | | Valor do atributo `name` de slot no HTML | | | | Nome do `part` no seletor CSS `::part()` | | | | Nome da propriedade CSS personalizada dentro do componente no CSS | | | | Nome da propriedade CSS personalizada global no CSS | | | | Nome da classe global no CSS | | | # Localização O mdui usa inglês como padrão interno. Se precisar usar outro idioma, é necessário configurar o multilinguismo. ## Como usar {#usage} O mdui fornece três funções para implementar a funcionalidade multilíngue: - [`loadLocale`](/pt-br/docs/2/functions/loadLocale): Carrega o pacote de idioma. O parâmetro é uma função que recebe um código de idioma como argumento e retorna uma Promise. Quando o carregamento do pacote de idioma é concluído, a Promise é resolvida com o pacote de idioma correspondente. Certifique-se de chamar esta função no arquivo de entrada do projeto. - [`setLocale`](/pt-br/docs/2/functions/setLocale): Altera para o idioma especificado. O parâmetro é o novo código de idioma. Retorna uma Promise que será resolvida quando o novo pacote de idioma for carregado. - [`getLocale`](/pt-br/docs/2/functions/getLocale): Obtém o código de idioma atual. Exemplo de uso: ```js import { loadLocale } from 'mdui/functions/loadLocale.js'; import { setLocale } from 'mdui/functions/setLocale.js'; import { getLocale } from 'mdui/functions/getLocale.js'; // No ponto de entrada do projeto, chame loadLocale para carregar o pacote de idioma loadLocale((locale) => import(`../node_modules/mdui/locales/${locale}.js`)); // Chame esta função quando precisar mudar o idioma. Após a Promise ser resolvida, a mudança de idioma é bem-sucedida setLocale('zh-cn').then(() => { // Chamar getLocale obtém o código de idioma atual console.log(getLocale()); // zh-cn }); ``` ## Eventos de estado {#event} No início, fim ou falha da mudança de idioma, o evento `mdui-localize-status` é acionado no `window`. Você pode monitorar este evento para executar operações personalizadas, como gravar o código de idioma em um cookie após a mudança bem-sucedida. A propriedade `detail.status` do evento descreve qual mudança de estado ocorreu. Os valores possíveis incluem: `loading`, `ready`, `error`: | `detail.status` | Descrição | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `loading` |

Começando a carregar um novo pacote de idioma.

O objeto `detail` contém:

loadingLocale: o código de idioma do novo pacote que está sendo carregado.

| | `ready` |

O novo pacote de idioma foi carregado com sucesso.

O objeto `detail` contém:

readyLocale: o código de idioma do novo pacote carregado.

| | `error` |

Falha ao carregar o novo pacote de idioma.

O objeto `detail` contém:

errorLocale: o código de idioma do pacote que falhou.
errorMessage: a mensagem de erro da falha.

| Exemplo de uso: ```js window.addEventListener('mdui-localize-status', (event) => { if (event.detail.status === 'loading') { console.log( `Começando a carregar o novo pacote de idioma: ${event.detail.loadingLocale}`, ); } else if (event.detail.status === 'ready') { console.log( `Novo pacote de idioma ${event.detail.readyLocale} carregado com sucesso`, ); } else if (event.detail.status === 'error') { console.error( `Falha ao carregar o novo pacote de idioma ${event.detail.errorLocale}: ${event.detail.errorMessage}`, ); } }); ``` ## Formas de carregar pacotes de idioma {#load-locale} ### Lazy loading {#lazy-load} Usar [importação dinâmica](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) permite baixar o pacote de idioma correspondente apenas quando você alterna para esse idioma. Este é o método mais recomendado. ```js import { loadLocale } from 'mdui/functions/loadLocale.js'; loadLocale((locale) => import(`../node_modules/mdui/locales/${locale}.js`)); ``` ### Pré-carregamento {#pre-load} Baixe todos os pacotes de idioma necessários durante o carregamento da página. Isso elimina a necessidade de baixar novamente ao alternar o idioma, tornando a mudança mais rápida. ```js import { loadLocale } from 'mdui/functions/loadLocale.js'; const localizedTemplates = new Map([ ['zh-cn', import(`../node_modules/mdui/locales/zh-cn.js`)], ['zh-tw', import(`../node_modules/mdui/locales/zh-tw.js`)], ]); loadLocale(async (locale) => localizedTemplates.get(locale)); ``` ### Importação estática {#static-imports} Este método permite empacotar todos os pacotes de idioma necessários junto com o código do seu projeto em um único arquivo, não sendo mais necessário baixar os pacotes de idioma separadamente. ```js import { loadLocale } from 'mdui/functions/loadLocale.js'; import * as locale_zh_cn from 'mdui/locales/zh-cn.js'; import * as locale_zh_tw from 'mdui/locales/zh-tw.js'; const localizedTemplates = new Map([ ['zh-cn', locale_zh_cn], ['zh-tw', locale_zh_tw], ]); loadLocale(async (locale) => localizedTemplates.get(locale)); ``` ## Carregando pacotes de idioma via CDN {#cdn} Se você está usando o mdui via CDN, pode carregar os pacotes de idioma diretamente do CDN. Exemplo de uso: ```html ``` ## Idiomas suportados {#languages} Atualmente, o mdui suporta os seguintes idiomas: | Idioma | Código | | ------------------------------ | ------ | | Árabe | ar-eg | | Azerbaijano | az-az | | Búlgaro | bg-bg | | Bengali (Bangladesh) | bn-bd | | Bielorrusso | be-by | | Catalão | ca-es | | Tcheco | cs-cz | | Dinamarquês | da-dk | | Alemão | de-de | | Grego | el-gr | | Inglês | en-gb | | Inglês (Americano) | en-us | | Espanhol | es-es | | Estoniano | et-ee | | Persa | fa-ir | | Finlandês | fi-fi | | Francês (Bélgica) | fr-be | | Francês (Canadá) | fr-ca | | Francês (França) | fr-fr | | Irlandês | ga-ie | | Galego (Espanha) | gl-es | | Hebraico | he-il | | Hindi | hi-in | | Croata | hr-hr | | Húngaro | hu-hu | | Armênio | hy-am | | Indonésio | id-id | | Italiano | it-it | | Islandês | is-is | | Japonês | ja-jp | | Georgiano | ka-ge | | Khmer | km-kh | | Curdo do Norte | kmr-iq | | Kannada | kn-in | | Cazaque | kk-kz | | Coreano | ko-kr | | Lituano | lt-lt | | Letão | lv-lv | | Macedônio | mk-mk | | Malaiala | ml-in | | Mongol | mn-mn | | Malaio (Malásia) | ms-my | | Norueguês | nb-no | | Nepalês | ne-np | | Holandês (Bélgica) | nl-be | | Holandês | nl-nl | | Polonês | pl-pl | | Português (Brasil) | pt-br | | Português | pt-pt | | Romeno | ro-ro | | Russo | ru-ru | | Eslovaco | sk-sk | | Sérvio | sr-rs | | Esloveno | sl-si | | Sueco | sv-se | | Tâmil | ta-in | | Tailandês | th-th | | Turco | tr-tr | | Urdu (Paquistão) | ur-pk | | Ucraniano | uk-ua | | Vietnamita | vi-vn | | Chinês Simplificado | zh-cn | | Chinês Tradicional (Hong Kong) | zh-hk | | Chinês Tradicional (Taiwan) | zh-tw | ## Enviar novas traduções {#contribute} Para contribuir com novas traduções ou melhorar as traduções existentes, abra um Pull Request no Github. Os pacotes de idioma estão localizados em [`packages/mdui/src/xliff`](https://github.com/zdhxiong/mdui/tree/v2/packages/mdui/src/xliff). Você pode editar diretamente no Github. # Perguntas frequentes Abaixo estão algumas perguntas comuns da comunidade mdui e respostas oficiais. Recomenda-se procurar por perguntas semelhantes antes de fazer uma pergunta. ## Por que usar tags auto-fechadas não exibe o componente? {#no-self-closing} mdui é uma biblioteca de componentes baseada em Web Components. A especificação Web Components não suporta tags auto-fechadas. Portanto, certifique-se de adicionar uma tag de fechamento para os componentes mdui. ```html

``` ## Como ocultar componentes antes que eles sejam carregados? {#waiting-load} Como os componentes mdui são registrados via JavaScript, antes que o arquivo JS seja carregado e o componente registrado, ele pode aparecer temporariamente sem estilo. Os dois métodos a seguir podem resolver esse problema: Um método é usar o pseudo-classe CSS [`:defined`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Selectors/:defined) para ocultar componentes mdui não registrados. O seguinte código CSS ocultará todos os componentes mdui não registrados e os exibirá imediatamente após o registro: ```css :not(:defined) { visibility: hidden; } ``` Outro método é usar o método JavaScript [`customElements.whenDefined()`](https://developer.mozilla.org/pt-BR/docs/Web/API/CustomElementRegistry/whenDefined). Este método retorna uma promise que é resolvida quando o componente especificado é registrado. Para lidar com casos em que alguns componentes não podem ser carregados devido a problemas, você pode usar [`Promise.allSettled()`](https://developer.mozilla.org/pt-BR/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled). O exemplo a seguir oculta `` com `opacity: 0` e, em seguida, exibe a página com um efeito fade-in após o registro dos componentes. O exemplo usa `Promise.allSettled()` para aguardar a conclusão de todas as promises, garantindo que a página seja exibida normalmente mesmo se algum componente não puder ser carregado: ```html ``` # LLMs.txt O mdui oferece `llms.txt` e `llms-full.txt`, usados para fornecer contexto preciso e pesquisável para LLMs (Grandes Modelos de Linguagem), ajudando a IA a responder perguntas relacionadas ao mdui de forma mais confiável. ## Use o llms.txt para fornecer contexto à IA {#context} Dois arquivos disponíveis: - `llms.txt`: https://www.mdui.org/pt-br/docs/2/llms.txt - `llms-full.txt`: https://www.mdui.org/pt-br/docs/2/llms-full.txt `llms.txt` é um índice simplificado, ideal para modelos que conseguem acessar a internet e buscar as páginas Markdown necessárias pelos links, ou para oferecer uma visão geral do projeto. `llms-full.txt` contém o contexto completo, incluindo todo o conteúdo das páginas em `llms.txt`, ideal para modelos sem acesso à internet ou quando você precisa fornecer todo o contexto de uma só vez. ## Versão Markdown da documentação {#md-mirror} Cada página da documentação tem sua versão Markdown: basta adicionar `.md` no final da URL da página (adicione `index.md` para a página inicial). Exemplos: https://www.mdui.org/pt-br/docs/2/components/button → https://www.mdui.org/pt-br/docs/2/components/button.md https://www.mdui.org/pt-br/docs/2/ → https://www.mdui.org/pt-br/docs/2/index.md Use o link Markdown diretamente ou seu conteúdo em texto simples como contexto para obter respostas mais focadas e precisas. ## Como usar no ChatGPT, Claude e outras ferramentas {#how-to-use} Dependendo dos recursos do modelo (acesso à internet/upload de arquivos), escolha uma ou combine as opções abaixo: 1. Cole o conteúdo: Cole o conteúdo de `llms-full.txt` como prompt de sistema ou primeira mensagem. Exemplo: “Abaixo está o contexto do mdui. Responda às próximas perguntas exclusivamente com base nele; Em caso de conflito, este contexto tem prioridade:\n\n[cole o conteúdo de llms-full.txt]”. 2. Enviar arquivo: Envie `llms-full.txt` (ou `llms.txt`) e mencione na primeira mensagem “use o anexo como contexto principal”. Exemplo: “Com base na documentação do mdui anexada, forneça o uso e as armadilhas comuns do ``”. 3. Leitura online: Forneça o link para `llms.txt` ou `llms-full.txt` na conversa. Exemplo: “Leia e siga https://www.mdui.org/pt-br/docs/2/llms-full.txt como contexto e responda minhas perguntas sobre o mdui”. 4. Aponte para uma página específica: Ao discutir apenas um componente/função específica, forneça diretamente o endereço Markdown dessa página. Exemplo: “Leia https://www.mdui.org/pt-br/docs/2/components/button.md e, com base nesse documento, forneça três práticas recomendadas”. **Dica**: Você pode clicar no ícone no canto superior direito da página para copiar os links acima com um clique, abrir a versão Markdown da página atual ou abrir a página atual ou `llms-full.txt` como contexto no ChatGPT. # Servidor MCP O mdui oferece um servidor [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) dedicado, `@mdui/mcp`, que fornece localmente recursos de consulta para componentes, ícones, propriedades CSS personalizadas e documentação para agentes de IA. Ele pode ser usado com ferramentas de desenvolvimento como Claude Code, Cursor, GitHub Copilot para ajudar na geração de código e melhorar o uso dos componentes e estilos do mdui. ## Ferramentas {#tools} O servidor MCP do mdui oferece as seguintes ferramentas para o agente de IA: - `list_components`: Lista todos os componentes do mdui. - `get_component_metadata`: Obtém metadados detalhados da API de um componente específico. - `list_css_classes`: Lista nomes de classes CSS globais. - `list_css_variables`: Lista propriedades CSS personalizadas globais. - `list_documents`: Lista todos os documentos. - `get_document`: Obtém o conteúdo completo de um documento específico. - `list_icon_codes`: Lista códigos de ícones que podem ser usados em atributos ou APIs. - `list_icon_components`: Lista componentes de ícone independentes e suas declarações de importação ESM. ## Como usar {#usage} O servidor MCP oferece suporte apenas para [transporte stdio](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio) e pode ser usado diretamente em clientes como VS Code, Cursor, Claude Code, Windsurf, Zed, além de outros agentes de IA que suportam o protocolo stdio. ### VS Code {#vscode} > Certifique-se de ter instalado as extensões [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) e [GitHub Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat). 1. Crie o diretório `.vscode` na raiz do projeto e, dentro dele, o arquivo `mcp.json` com a seguinte configuração: ```json { "servers": { "mdui": { "command": "npx", "args": ["-y", "@mdui/mcp"] } } } ``` 2. Clique no botão “Iniciar” no arquivo `mcp.json`. 3. Comece a conversar no GitHub Copilot Chat. ### Cursor {#cursor} 1. Crie ou edite o arquivo `.cursor/mcp.json` na raiz do projeto com a seguinte configuração: ```json { "mcpServers": { "mdui": { "command": "npx", "args": ["-y", "@mdui/mcp"] } } } ``` 2. Acesse Configurações > Configurações do Cursor > MCP & Integrations e ative o servidor mdui. 3. Comece a conversar no Cursor Chat. ### Claude Code {#claude-code} 1. Execute o seguinte comando no terminal para adicionar o servidor MCP mdui: ```bash claude mcp add mdui -- npx -y @mdui/mcp ``` 2. Em seguida, execute `claude` para iniciar a sessão. 3. Digite o prompt para começar a usar. ### Windsurf {#windsurf} 1. Acesse Configurações > Configurações do Windsurf > Cascade 2. Clique em Gerenciar MCPs e depois em “Ver configuração bruta”. Adicione ao arquivo de configuração: ```json { "mcpServers": { "mdui": { "command": "npx", "args": ["-y", "@mdui/mcp"] } } } ``` > Se o servidor MCP não aparecer automaticamente, clique em Atualizar para atualizar a lista. 3. Digite o prompt para começar a conversar. ### Zed {#zed} 1. Abra Configurações > Abrir Configurações e adicione a seguinte configuração ao arquivo `settings.json`: ```json { "context_servers": { "mdui": { "source": "custom", "command": "npx", "args": ["-y", "@mdui/mcp"] } } } ``` 2. Digite o prompt para começar a usar. ### Cliente MCP personalizado {#custom} Ao usar um cliente MCP personalizado no ambiente local ou de desenvolvimento, adicione o servidor ao arquivo de configuração do cliente. Exemplos: ```json { "mcpServers": { "mdui": { "command": "npx", "args": ["-y", "@mdui/mcp"] } } } ``` # Modo escuro Todos os componentes do mdui suportam modo escuro e podem alternar automaticamente o tema com base nas configurações do sistema operacional. Você pode clicar no ícone no canto superior direito da página de documentação a qualquer momento para alternar o tema e ver a aparência dos componentes em diferentes temas. Para usar o modo escuro, basta adicionar a classe `mdui-theme-dark` na tag ``: ```html ``` Para que o tema mude automaticamente com base nas configurações do sistema operacional, basta adicionar a classe `mdui-theme-auto` na tag ``: ```html ``` Você também pode usar temas diferentes em diferentes partes da página. Por exemplo, no exemplo a seguir, o modo escuro é definido no ``, mas uma classe `mdui-theme-light` é adicionada a um `

` na página. Assim, os elementos dentro deste `

` serão exibidos em modo claro, enquanto o restante da página permanecerá em modo escuro: ```html

``` Além de adicionar classes CSS diretamente, o mdui fornece duas funções para manipular temas de forma mais conveniente: - [`getTheme`](/pt-br/docs/2/functions/getTheme): obtém o tema da página atual ou de um elemento especificado. - [`setTheme`](/pt-br/docs/2/functions/setTheme): define o tema da página atual ou de um elemento especificado. --- É importante notar que o mdui define estilos `color` e `background-color` nos seletores `:root`, `.mdui-theme-light`, `.mdui-theme-dark` e `.mdui-theme-auto`. Se você não gostar desses estilos padrão, pode sobrescrevê-los. O exemplo a seguir define o fundo da página como branco puro e o texto como preto puro no modo claro; e no modo escuro, o fundo como preto puro e o texto como branco puro: ```css :root, .mdui-theme-light { color: #000; background-color: #fff; } .mdui-theme-dark { color: #fff; background-color: #000; } @media (prefers-color-scheme: dark) { .mdui-theme-auto { color: #fff; background-color: #000; } } ``` # Cor dinâmica O mdui fornece um recurso de cor dinâmica. Basta fornecer um valor de cor e o mdui gerará automaticamente um esquema de cores completo. Além disso, o mdui também suporta a extração da cor primária de um papel de parede especificado e a geração de um esquema de cores com base nela. Você pode clicar no ícone no canto superior direito da página de documentação a qualquer momento para alternar o esquema de cores e ver a aparência dos componentes em diferentes esquemas de cores. Um esquema de cores é, na verdade, um conjunto de propriedades CSS personalizadas. Os valores de cor nos componentes do mdui referenciam esse conjunto de propriedades CSS personalizadas, portanto, o esquema de cores de todos os componentes pode ser atualizado de uma só vez. Consulte [Design tokens - Cores](/pt-br/docs/2/styles/design-tokens#color) para a lista completa de propriedades CSS personalizadas. ## Gerar esquema de cores {#color-scheme} Você pode usar a função [`setColorScheme`](/pt-br/docs/2/functions/setColorScheme) para gerar um esquema de cores. Esta função aceita um valor de cor hexadecimal como parâmetro, gera um esquema de cores e define o elemento `` da página com esse esquema. Por exemplo: ```js import { setColorScheme } from 'mdui/functions/setColorScheme.js'; // Gera um esquema de cores com base em #0061a4 e define o com esse esquema setColorScheme('#0061a4'); ``` Você também pode especificar a propriedade `target` no segundo parâmetro para indicar em qual elemento definir o esquema de cores. Por exemplo: ```js import { setColorScheme } from 'mdui/functions/setColorScheme.js'; // Gera um esquema de cores com base em #0061a4 e define o elemento .foo com esse esquema setColorScheme('#0061a4', { target: document.querySelector('.foo'), }); ``` Por padrão, o esquema de cores gerado contém apenas as cores listadas em [Design tokens - Cores](/pt-br/docs/2/styles/design-tokens#color). Você pode especificar a propriedade `customColors` no segundo parâmetro. O mdui gerará um conjunto de grupos de cores personalizadas com base nos nomes e valores de cores personalizados fornecidos. Por exemplo: ```js import { setColorScheme } from 'mdui/functions/setColorScheme.js'; // Gera um esquema de cores com base em #0061a4, modifica o valor do grupo de cores error existente e adiciona um novo grupo de cores music setColorScheme('#0061a4', { customColors: [ { name: 'error', value: '#69F0AE', }, { name: 'music', value: '#FFC107', }, ], }); ``` Um grupo de cores personalizadas contém quatro propriedades CSS personalizadas: - `--mdui-color-{name}` - `--mdui-color-on-{name}` - `--mdui-color-{name}-container` - `--mdui-color-on-{name}-container` O `{name}` é o nome da cor personalizada passado em `customColors`. O nome da cor personalizada pode ser um nome de cor já existente no esquema de cores padrão, como `primary`, `secondary`, `tertiary`, `error`, etc. Se você especificar esses valores como nomes de cores personalizadas, as quatro propriedades CSS personalizadas correspondentes no esquema de cores gerado usarão os valores de cor especificados. Por exemplo, no exemplo acima, especificamos um nome de cor personalizada `error`. Como `error` já existe no esquema de cores padrão e suas propriedades CSS personalizadas correspondentes são usadas pelos componentes mdui para indicar estado de erro, agora o valor da cor é definido como um valor verde, portanto, o estado de erro nos componentes mdui também se tornará verde. O nome da cor personalizada também pode ser um novo nome, como `music` no exemplo acima, que não existe no esquema de cores padrão. Assim, o esquema de cores gerado incluirá quatro propriedades CSS personalizadas adicionais. Você pode referenciar essas propriedades CSS personalizadas em seus próprios estilos: ```html

Música

Contêiner de Música

``` Você também pode usar a função [`removeColorScheme`](/pt-br/docs/2/functions/removeColorScheme) para remover o esquema de cores gerado pelo método acima. Você pode passar um parâmetro para especificar de qual elemento remover o esquema de cores. Por padrão, ela remove o esquema de cores do ``. ## Extrair cor de papel de parede {#from-wallpaper} O mdui fornece a função [`getColorFromImage`](/pt-br/docs/2/functions/getColorFromImage) para extrair a cor primária de uma instância `Image` fornecida. Esta função retorna uma Promise cujo valor resolvido é o valor da cor em hexadecimal extraído. Você pode usar o valor de cor obtido desta função e chamar a função [`setColorScheme`](/pt-br/docs/2/functions/setColorScheme) descrita acima para definir o esquema de cores. Por exemplo: ```js import { getColorFromImage } from 'mdui/functions/getColorFromImage.js'; import { setColorScheme } from 'mdui/functions/setColorScheme.js'; const image = new Image(); image.src = 'image1.png'; getColorFromImage(image).then((color) => setColorScheme(color)); ``` # Tipografia O mdui fornece as classes CSS `mdui-prose` e `mdui-table`, especialmente para otimizar a aparência de artigos e tabelas. ## Estilo para artigos {#prose} Você pode adicionar a classe `mdui-prose` ao elemento pai de um artigo para otimizar a exibição de todo o artigo, incluindo o estilo de tabelas `` dentro do artigo. Por exemplo : ```html

Título

Texto do parágrafo

``` ## Estilo para tabelas {#table} Adicione a classe `mdui-table` ao elemento `` para otimizar a aparência da tabela. Por exemplo : ```html

``` Para permitir que o elemento `` role horizontalmente dentro do elemento pai, adicione a classe `mdui-table` ao elemento pai. Por exemplo : ```html

``` # Design tokens Design tokens é uma estratégia para gerenciar sistemas de design. Ela abstrai todos os elementos reutilizáveis em um sistema de design (como cores, fontes, espaçamentos, etc.) em variáveis independentes, permitindo gerenciamento e aplicação uniformes em todo o sistema de design. O mdui usa propriedades CSS personalizadas globais para implementar design tokens. Isso significa que você pode modificar globalmente a aparência de todos os componentes do mdui simplesmente alterando as propriedades CSS personalizadas. Além disso, para seus próprios estilos, é recomendado priorizar a referência às propriedades CSS personalizadas para garantir que seus estilos estejam alinhados com os componentes do mdui e também para que seus estilos sejam atualizados junto com a cor dinâmica. ## Cores {#color} O mdui fornece um conjunto de propriedades CSS personalizadas para o modo claro e outro para o modo escuro. No modo claro, o nome da propriedade CSS personalizada é `--mdui-color-{name}-light`, onde `{name}` é o nome da cor; no modo escuro, é `--mdui-color-{name}-dark`. Além disso, o mdui fornece um conjunto de propriedades CSS personalizadas chamadas `--mdui-color-{name}`. Essas propriedades referenciam `--mdui-color-{name}-light` no modo claro e `--mdui-color-{name}-dark` no modo escuro, portanto, alternam automaticamente de acordo com o modo claro ou escuro atual. Se você precisar modificar os valores de algumas propriedades CSS personalizadas de cor, precisará modificar ambas as propriedades `--mdui-color-{name}-light` e `--mdui-color-{name}-dark`. Ao ler as propriedades CSS personalizadas, use diretamente a propriedade `--mdui-color-{name}`. O valor da propriedade CSS personalizada são os três valores RGB separados por `,`. O exemplo a seguir demonstra o uso das propriedades CSS personalizadas de cor: ```css /* Modificar o valor da cor primary */ :root { --mdui-color-primary-light: 103, 80, 164; --mdui-color-primary-dark: 208, 188, 255; } /* Definir o fundo do elemento foo como primary */ .foo { background-color: rgb(var(--mdui-color-primary)); } /* Definir o fundo do elemento bar como primary com 0.8 de opacidade */ .bar { background-color: rgba(var(--mdui-color-primary), 0.8); } ``` Se você precisar criar um esquema de cores totalmente novo, é recomendado usar a função [`setColorScheme`](/pt-br/docs/2/functions/setColorScheme), que gera um esquema de cores completo a partir de um valor de cor fornecido.

Nome da cor	Propriedade CSS personalizada	Valor padrão
Primary	`--mdui-color-primary-light`	`103, 80, 164`
	`--mdui-color-primary-dark`	`208, 188, 255`
	`--mdui-color-primary`
Primary container	`--mdui-color-primary-container-light`	`234, 221, 255`
	`--mdui-color-primary-container-dark`	`79, 55, 139`
	`--mdui-color-primary-container`
On primary	`--mdui-color-on-primary-light`	`255, 255, 255`
	`--mdui-color-on-primary-dark`	`55, 30, 115`
	`--mdui-color-on-primary`
On primary container	`--mdui-color-on-primary-container-light`	`33, 0, 94`
	`--mdui-color-on-primary-container-dark`	`234, 221, 255`
	`--mdui-color-on-primary-container`
Inverse primary	`--mdui-color-inverse-primary-light`	`208, 188, 255`
	`--mdui-color-inverse-primary-dark`	`103, 80, 164`
	`--mdui-color-inverse-primary`
Secondary	`--mdui-color-secondary-light`	`98, 91, 113`
	`--mdui-color-secondary-dark`	`204, 194, 220`
	`--mdui-color-secondary`
Secondary container	`--mdui-color-secondary-container-light`	`232, 222, 248`
	`--mdui-color-secondary-container-dark`	`74, 68, 88`
	`--mdui-color-secondary-container`
On secondary	`--mdui-color-on-secondary-light`	`255, 255, 255`
	`--mdui-color-on-secondary-dark`	`51, 45, 65`
	`--mdui-color-on-secondary`
On secondary container	`--mdui-color-on-secondary-container-light`	`30, 25, 43`
	`--mdui-color-on-secondary-container-dark`	`232, 222, 248`
	`--mdui-color-on-secondary-container`
Tertiary	`--mdui-color-tertiary-light`	`125, 82, 96`
	`--mdui-color-tertiary-dark`	`239, 184, 200`
	`--mdui-color-tertiary`
Tertiary container	`--mdui-color-tertiary-container-light`	`255, 216, 228`
	`--mdui-color-tertiary-container-dark`	`99, 59, 72`
	`--mdui-color-tertiary-container`
On tertiary	`--mdui-color-on-tertiary-light`	`255, 255, 255`
	`--mdui-color-on-tertiary-dark`	`73, 37, 50`
	`--mdui-color-on-tertiary`
On tertiary container	`--mdui-color-on-tertiary-container-light`	`55, 11, 30`
	`--mdui-color-on-tertiary-container-dark`	`255, 216, 228`
	`--mdui-color-on-tertiary-container`
Surface	`--mdui-color-surface-light`	`254, 247, 255`
	`--mdui-color-surface-dark`	`20, 18, 24`
	`--mdui-color-surface`
Surface dim	`--mdui-color-surface-dim-light`	`222, 216, 225`
	`--mdui-color-surface-dim-dark`	`20, 18, 24`
	`--mdui-color-surface-dim`
Surface bright	`--mdui-color-surface-bright-light`	`254, 247, 255`
	`--mdui-color-surface-bright-dark`	`59, 56, 62`
	`--mdui-color-surface-bright`
Surface container lowest	`--mdui-color-surface-container-lowest-light`	`255, 255, 255`
	`--mdui-color-surface-container-lowest-dark`	`15, 13, 19`
	`--mdui-color-surface-container-lowest`
Surface container low	`--mdui-color-surface-container-low-light`	`247, 242, 250`
	`--mdui-color-surface-container-low-dark`	`29, 27, 32`
	`--mdui-color-surface-container-low`
Surface container	`--mdui-color-surface-container-light`	`243, 237, 247`
	`--mdui-color-surface-container-dark`	`33, 31, 38`
	`--mdui-color-surface-container`
Surface container high	`--mdui-color-surface-container-high-light`	`236, 230, 240`
	`--mdui-color-surface-container-high-dark`	`43, 41, 48`
	`--mdui-color-surface-container-high`
Surface container highest	`--mdui-color-surface-container-highest-light`	`230, 224, 233`
	`--mdui-color-surface-container-highest-dark`	`54, 52, 59`
	`--mdui-color-surface-container-highest`
Surface variant	`--mdui-color-surface-variant-light`	`231, 224, 236`
	`--mdui-color-surface-variant-dark`	`73, 69, 79`
	`--mdui-color-surface-variant`
On surface	`--mdui-color-on-surface-light`	`28, 27, 31`
	`--mdui-color-on-surface-dark`	`230, 225, 229`
	`--mdui-color-on-surface`
On surface variant	`--mdui-color-on-surface-variant-light`	`73, 69, 78`
	`--mdui-color-on-surface-variant-dark`	`202, 196, 208`
	`--mdui-color-on-surface-variant`
Inverse surface	`--mdui-color-inverse-surface-light`	`49, 48, 51`
	`--mdui-color-inverse-surface-dark`	`230, 225, 229`
	`--mdui-color-inverse-surface`
Inverse on surface	`--mdui-color-inverse-on-surface-light`	`244, 239, 244`
	`--mdui-color-inverse-on-surface-dark`	`49, 48, 51`
	`--mdui-color-inverse-on-surface`
Background	`--mdui-color-background-light`	`254, 247, 255`
	`--mdui-color-background-dark`	`20, 18, 24`
	`--mdui-color-background`
On background	`--mdui-color-on-background-light`	`28, 27, 31`
	`--mdui-color-on-background-dark`	`230, 225, 229`
	`--mdui-color-on-background`
Error	`--mdui-color-error-light`	`179, 38, 30`
	`--mdui-color-error-dark`	`242, 184, 181`
	`--mdui-color-error`
Error container	`--mdui-color-error-container-light`	`249, 222, 220`
	`--mdui-color-error-container-dark`	`140, 29, 24`
	`--mdui-color-error-container`
On error	`--mdui-color-on-error-light`	`255, 255, 255`
	`--mdui-color-on-error-dark`	`96, 20, 16`
	`--mdui-color-on-error`
On error container	`--mdui-color-on-error-container-light`	`65, 14, 11`
	`--mdui-color-on-error-container-dark`	`249, 222, 220`
	`--mdui-color-on-error-container`
Outline	`--mdui-color-outline-light`	`121, 116, 126`
	`--mdui-color-outline-dark`	`147, 143, 153`
	`--mdui-color-outline`
Outline variant	`--mdui-color-outline-variant-light`	`196, 199, 197`
	`--mdui-color-outline-variant-dark`	`68, 71, 70`
	`--mdui-color-outline-variant`
Shadow	`--mdui-color-shadow-light`	`0, 0, 0`
	`--mdui-color-shadow-dark`	`0, 0, 0`
	`--mdui-color-shadow`
Surface tint	`--mdui-color-surface-tint-color-light`	`103, 80, 164`
	`--mdui-color-surface-tint-color-dark`	`208, 188, 255`
	`--mdui-color-surface-tint-color`
Scrim	`--mdui-color-scrim-light`	`0, 0, 0`
	`--mdui-color-scrim-dark`	`0, 0, 0`
	`--mdui-color-scrim`

## Cantos arredondados {#shape-corner} O mdui fornece 7 tamanhos diferentes de cantos arredondados. O exemplo a seguir demonstra como usar essas propriedades CSS personalizadas de cantos arredondados: ```css /* Modificar o tamanho do canto extra-small */ :root { --mdui-shape-corner-extra-small: 0.3rem; } /* Definir o canto do elemento foo como extra-small */ .foo { border-radius: var(--mdui-shape-corner-extra-small); } ``` | Propriedade CSS personalizada | Valor padrão | Exemplo | | --------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------- | | `--mdui-shape-corner-none` | `0` |

| | `--mdui-shape-corner-extra-small` | `0.25rem` |

| | `--mdui-shape-corner-small` | `0.5rem` |

| | `--mdui-shape-corner-medium` | `0.75rem` |

| | `--mdui-shape-corner-large` | `1rem` |

| | `--mdui-shape-corner-extra-large` | `1.75rem` |

| | `--mdui-shape-corner-full` | `1000rem` |

| ## Tipografia {#typescale} O mdui fornece 15 estilos de texto diferentes, incluindo Display large, Display medium, Display small, Headline large, Headline medium, Headline small, Title large, Title medium, Title small, Label large, Label medium, Label small, Body large, Body medium, Body small. Exemplo de uso: ```css /* Modificar o estilo de texto Body large */ :root { --mdui-typescale-body-large-line-height: 1.6rem; --mdui-typescale-body-large-size: 1.2rem; --mdui-typescale-body-large-tracking: 0.01rem; --mdui-typescale-body-large-weight: 400; } /* Definir o estilo de texto do elemento foo como Body large */ .foo { line-height: var(--mdui-typescale-body-large-line-height); font-size: var(--mdui-typescale-body-large-size); letter-spacing: var(--mdui-typescale-body-large-tracking); font-weight: var(--mdui-typescale-body-large-weight); } ```

Propriedade CSS personalizada	Valor padrão	Exemplo
`--mdui-typescale-display-large-line-height`	`4rem`	Display large
`--mdui-typescale-display-large-size`	`3.5625rem`
`--mdui-typescale-display-large-tracking`	`0`
`--mdui-typescale-display-large-weight`	`400`
`--mdui-typescale-display-medium-line-height`	`3.25rem`	Display medium
`--mdui-typescale-display-medium-size`	`2.8125rem`
`--mdui-typescale-display-medium-tracking`	`0`
`--mdui-typescale-display-medium-weight`	`400`
`--mdui-typescale-display-small-line-height`	`2.75rem`	Display small
`--mdui-typescale-display-small-size`	`2.25rem`
`--mdui-typescale-display-small-tracking`	`0`
`--mdui-typescale-display-small-weight`	`400`
`--mdui-typescale-headline-large-line-height`	`2.5rem`	Headline large
`--mdui-typescale-headline-large-size`	`2rem`
`--mdui-typescale-headline-large-tracking`	`0`
`--mdui-typescale-headline-large-weight`	`400`
`--mdui-typescale-headline-medium-line-height`	`2.25rem`	Headline medium
`--mdui-typescale-headline-medium-size`	`1.75rem`
`--mdui-typescale-headline-medium-tracking`	`0`
`--mdui-typescale-headline-medium-weight`	`400`
`--mdui-typescale-headline-small-line-height`	`2rem`	Headline small
`--mdui-typescale-headline-small-size`	`1.5rem`
`--mdui-typescale-headline-small-tracking`	`0`
`--mdui-typescale-headline-small-weight`	`400`
`--mdui-typescale-title-large-line-height`	`1.75rem`	Title large
`--mdui-typescale-title-large-size`	`1.375rem`
`--mdui-typescale-title-large-tracking`	`0`
`--mdui-typescale-title-large-weight`	`400`
`--mdui-typescale-title-medium-line-height`	`1.5rem`	Title medium
`--mdui-typescale-title-medium-size`	`1rem`
`--mdui-typescale-title-medium-tracking`	`0.009375rem`
`--mdui-typescale-title-medium-weight`	`500`
`--mdui-typescale-title-small-line-height`	`1.25rem`	Title small
`--mdui-typescale-title-small-size`	`0.875rem`
`--mdui-typescale-title-small-tracking`	`0.00625rem`
`--mdui-typescale-title-small-weight`	`500`
`--mdui-typescale-label-large-line-height`	`1.25rem`	Label large
`--mdui-typescale-label-large-size`	`0.875rem`
`--mdui-typescale-label-large-tracking`	`0.00625rem`
`--mdui-typescale-label-large-weight`	`500`
`--mdui-typescale-label-medium-line-height`	`1rem`	Label medium
`--mdui-typescale-label-medium-size`	`0.75rem`
`--mdui-typescale-label-medium-tracking`	`0.03125rem`
`--mdui-typescale-label-medium-weight`	`500`
`--mdui-typescale-label-small-line-height`	`0.375rem`	Label small
`--mdui-typescale-label-small-size`	`0.6875rem`
`--mdui-typescale-label-small-tracking`	`0.03125rem`
`--mdui-typescale-label-small-weight`	`500`
`--mdui-typescale-body-large-line-height`	`1.5rem`	Body large
`--mdui-typescale-body-large-size`	`1rem`
`--mdui-typescale-body-large-tracking`	`0.009375rem`
`--mdui-typescale-body-large-weight`	`400`
`--mdui-typescale-body-medium-line-height`	`1.25rem`	Body medium
`--mdui-typescale-body-medium-size`	`0.875rem`
`--mdui-typescale-body-medium-tracking`	`0.015625rem`
`--mdui-typescale-body-medium-weight`	`400`
`--mdui-typescale-body-small-line-height`	`1rem`	Body small
`--mdui-typescale-body-small-size`	`0.75rem`
`--mdui-typescale-body-small-tracking`	`0.025rem`
`--mdui-typescale-body-small-weight`	`400`

## Opacidade da camada de estado {#state-layer} Alguns componentes mdui adicionam uma camada semitransparente sobre eles durante a interação. Por exemplo, o componente [``](/pt-br/docs/2/components/button) exibe uma camada semitransparente quando o mouse está sobre ele, quando está focado, pressionado ou arrastado. Você pode modificar as propriedades CSS personalizadas para ajustar a opacidade dessas camadas. Exemplo de uso: ```css /* Modificar a opacidade das camadas de estado */ :root { --mdui-state-layer-hover: 0.08; --mdui-state-layer-focus: 0.12; --mdui-state-layer-pressed: 0.12; --mdui-state-layer-dragged: 0.16; } ``` | Propriedade CSS personalizada | Valor padrão | Exemplo | | ----------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------ | | `--mdui-state-layer-hover` | `0.08` |

| | `--mdui-state-layer-focus` | `0.12` |

| | `--mdui-state-layer-pressed` | `0.12` |

| | `--mdui-state-layer-dragged` | `0.16` |

| ## Elevação (sombras) {#elevation} Alguns componentes mdui têm efeitos de sombra para simular uma sensação de elevação na página. Você pode modificar as propriedades CSS personalizadas para ajustar os efeitos de sombra dos componentes. Exemplo de uso: ```css /* Modificar a sombra de nível 1 */ :root { --mdui-elevation-level1: 0 0.5px 1.5px 0 rgba(var(--mdui-color-shadow), 19%), 0 0 1px 0 rgba(var(--mdui-color-shadow), 3.9%); } /* Definir a sombra do elemento foo como nível 1 */ .foo { box-shadow: var(--mdui-elevation-level1); } ``` | Propriedade CSS personalizada | Valor padrão | Exemplo | | ----------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `--mdui-elevation-level0` | `none` |

| | `--mdui-elevation-level1` | `0 0.5px 1.5px 0 rgba(var(--mdui-color-shadow), 19%), 0 0 1px 0 rgba(var(--mdui-color-shadow), 3.9%)` |

| | `--mdui-elevation-level2` | `0 0.85px 3px 0 rgba(var(--mdui-color-shadow), 19%), 0 0.25px 1px 0 rgba(var(--mdui-color-shadow), 3.9%)` |

| | `--mdui-elevation-level3` | `0 1.25px 5px 0 rgba(var(--mdui-color-shadow), 19%), 0 0.3333px 1.5px 0 rgba(var(--mdui-color-shadow), 3.9%)` |

| | `--mdui-elevation-level4` | `0 1.85px 6.25px 0 rgba(var(--mdui-color-shadow), 19%), 0 0.5px 1.75px 0 rgba(var(--mdui-color-shadow), 3.9%)` |

| | `--mdui-elevation-level5` | `0 2.75px 9px 0 rgba(var(--mdui-color-shadow), 19%), 0 0.25px 3px 0 rgba(var(--mdui-color-shadow), 3.9%)` |

| ## Animações {#motion} As curvas de easing e durações das animações nos componentes mdui podem ser configuradas por meio de propriedades CSS personalizadas. Exemplo de uso: ```css /* Modificar a curva de easing standard e a duração short1 */ :root { --mdui-motion-easing-standard: cubic-bezier(0.2, 0, 0, 1); --mdui-motion-duration-short1: 40ms; } /* Definir a transição do elemento foo para usar a curva de easing standard e a duração short1 */ .foo { transition: all var(--mdui-motion-duration-short1) var(--mdui-motion-easing-standard); } ```

Tipo	Propriedade CSS personalizada	Valor padrão
Curvas de easing	`--mdui-motion-easing-linear`	`cubic-bezier(0, 0, 1, 1)`
	`--mdui-motion-easing-standard`	`cubic-bezier(0.2, 0, 0, 1)`
	`--mdui-motion-easing-standard-accelerate`	`cubic-bezier(0.3, 0, 1, 1)`
	`--mdui-motion-easing-standard-decelerate`	`cubic-bezier(0, 0, 0, 1)`
	`--mdui-motion-easing-emphasized`	`var(--mdui-motion-easing-standard)`
	`--mdui-motion-easing-emphasized-accelerate`	`cubic-bezier(0.3, 0, 0.8, 0.15)`
	`--mdui-motion-easing-emphasized-decelerate`	`cubic-bezier(0.05, 0.7, 0.1, 1)`
Duração	`--mdui-motion-duration-short1`	`50ms`
	`--mdui-motion-duration-short2`	`100ms`
	`--mdui-motion-duration-short3`	`150ms`
	`--mdui-motion-duration-short4`	`200ms`
	`--mdui-motion-duration-medium1`	`250ms`
	`--mdui-motion-duration-medium2`	`300ms`
	`--mdui-motion-duration-medium3`	`350ms`
	`--mdui-motion-duration-medium4`	`400ms`
	`--mdui-motion-duration-long1`	`450ms`
	`--mdui-motion-duration-long2`	`500ms`
	`--mdui-motion-duration-long3`	`550ms`
	`--mdui-motion-duration-long4`	`600ms`
	`--mdui-motion-duration-extra-long1`	`700ms`
	`--mdui-motion-duration-extra-long2`	`800ms`
	`--mdui-motion-duration-extra-long3`	`900ms`
	`--mdui-motion-duration-extra-long4`	`1000ms`

## Pontos de quebra responsivos {#breakpoint} O mdui fornece uma série de pontos de quebra responsivos que podem ser configurados por meio de propriedades CSS personalizadas. Exemplo de uso: ```css /* Modificar o valor do ponto de quebra sm */ :root { --mdui-breakpoint-sm: 560px; } ``` É importante notar que essas propriedades CSS personalizadas não podem ser usadas em media queries CSS. O exemplo a seguir está incorreto: ```css /* Uso incorreto. Não é possível usar propriedades CSS personalizadas em media queries */ @media (min-width: var(--mdui-breakpoint-sm)) { } ``` Se você precisar fazer verificações de pontos de quebra em JavaScript, use a função [`breakpoint`](/pt-br/docs/2/functions/breakpoint). | Propriedade CSS personalizada | Valor padrão | | ----------------------------- | ------------ | | `--mdui-breakpoint-xs` | `0px` | | `--mdui-breakpoint-sm` | `600px` | | `--mdui-breakpoint-md` | `840px` | | `--mdui-breakpoint-lg` | `1080px` | | `--mdui-breakpoint-xl` | `1440px` | | `--mdui-breakpoint-xxl` | `1920px` | # Integração com React Ao usar mdui no React, basta seguir as instruções de instalação na página [Instalação](/pt-br/docs/2/getting-started/installation#npm). ## Notas {#notes} Existem algumas limitações ao usar mdui no React. Essas limitações são gerais ao usar Web Components no React, não específicas da biblioteca de componentes mdui. ### Vinculação de eventos {#event-binding} Como o React não suporta eventos personalizados, ao usar os eventos fornecidos pelos componentes mdui, você precisa primeiro obter uma referência ao componente usando o atributo `ref`. Exemplo de uso de eventos de componentes mdui no React: ```js import { useEffect, useRef } from 'react'; import 'mdui/mdui.css'; import 'mdui/components/switch.js'; function App() { const switchRef = useRef(null); useEffect(() => { const handleToggle = () => { console.log('switch is toggled'); }; switchRef.current.addEventListener('change', handleToggle); return () => { switchRef.current.removeEventListener('change', handleToggle); }; }, []); return ; } export default App; ``` ### Declaração de tipos TypeScript para JSX {#jsx-typescript} Se você estiver usando mdui em um arquivo TypeScript (.tsx), é necessário adicionar a declaração de tipos TypeScript. Você precisa adicionar manualmente a referência ao arquivo de declaração de tipos do mdui em um arquivo .d.ts do seu projeto: ```ts /// ``` # Integração com Vue Ao usar mdui no Vue, primeiro instale seguindo as instruções na página [Instalação](/pt-br/docs/2/getting-started/installation#npm) e, em seguida, faça algumas configurações necessárias. ## Configuração {#configuration} Você precisa configurar o Vue para que ele não interprete os componentes mdui como componentes Vue. No arquivo `vite.config`, defina a opção `compilerOptions.isCustomElement`: ```js // vite.config.js import vue from '@vitejs/plugin-vue'; export default { plugins: [ vue({ template: { compilerOptions: { // Todas as tags que começam com mdui- são componentes mdui isCustomElement: (tag) => tag.startsWith('mdui-'), }, }, }), ], }; ``` Para mais informações sobre esta configuração, consulte a [documentação oficial do Vue](https://pt.vuejs.org/guide/extras/web-components.html#using-custom-elements-in-vue). ## Notas {#notes} ### Ligação de dados bidirecional {#data-binding} Em componentes mdui, você não pode usar `v-model` para ligação bidirecional de dados. Você precisa lidar manualmente com a vinculação e atualização dos dados. Por exemplo: ```html ``` ### Configuração do eslint {#eslint} Se você estiver usando [`eslint-plugin-vue`](https://www.npmjs.com/package/eslint-plugin-vue), adicione a seguinte regra em `.eslintrc.js`: ```js rules: { 'vue/no-deprecated-slot-attribute': 'off' } ``` # Integração com Angular Ao usar mdui no Angular, primeiro instale seguindo as instruções na página [Instalação](/pt-br/docs/2/getting-started/installation#npm) e, em seguida, faça algumas configurações necessárias. ## Configuração {#configuration} Primeiro, precisamos habilitar o suporte a Web Components no Angular. Exemplo: ```js import { BrowserModule } from '@angular/platform-browser'; import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'; import { AppComponent } from './app.component'; @NgModule({ declarations: [AppComponent], imports: [BrowserModule], providers: [], bootstrap: [AppComponent], schemas: [CUSTOM_ELEMENTS_SCHEMA], }) export class AppModule {} ``` Após a configuração, podemos importar e usar os componentes mdui no código do componente Angular: ```js import { Dialog } from 'mdui/components/dialog.js'; @Component({ selector: 'app-dialog-example', template: `

Dialog Content

` }) export class DialogExampleComponent implements OnInit { // Use @ViewChild para obter a referência do elemento #dialog @ViewChild('dialog') dialog?: ElementRef; ... constructor(...) { } ngOnInit() { } ... openDialog() { // Use nativeElement para acessar o componente mdui this.dialog?.nativeElement.open = true; } } ``` # Integração com outros frameworks mdui é desenvolvido com Web Components, que são suportados nativamente pelos navegadores, permitindo seu uso em todos os frameworks web. Abaixo estão listadas as formas de usar o mdui em alguns frameworks comuns. ## Aurelia {#Aurelia} Após seguir as instruções de instalação na página [Instalação](/pt-br/docs/2/getting-started/installation#npm), você também precisa instalar e configurar um pacote adicional (aplicável apenas ao Aurelia 2): ```bash npm install aurelia-mdui --save ``` Em seguida, registre-o em seu aplicativo: ```typescript import { MduiWebTask } from 'aurelia-mdui'; Aurelia.register(MduiWebTask).app(MyApp).start(); ``` **Nota** Por favor, relate os erros em [https://github.com/mreiche/aurelia-mdui](https://github.com/mreiche/aurelia-mdui) ## WebCell {#WebCell} Ao usar mdui no [WebCell](https://web-cell.dev/), basta seguir as instruções de instalação na página [Instalação](/pt-br/docs/2/getting-started/installation#npm). O suporte a Web Components, TypeScript e JSX são recursos primários e funcionam prontamente. Ou você pode usar o [modelo de repositório GitHub oficial](https://github.com/EasyWebApp/WebCell-mobile) para [criar um novo projeto com um clique](https://github.com/new?template_name=WebCell-mobile&template_owner=EasyWebApp). # Componente Avatar O Avatar representa uma pessoa ou objeto, suportando várias formas, incluindo imagens, ícones ou caracteres. ## Como usar {#usage} Importe o componente quando necessário: ```js import 'mdui/components/avatar.js'; ``` Importe o tipo TypeScript do componente quando necessário: ```ts import type { Avatar } from 'mdui/components/avatar.js'; ``` Exemplo de uso: ```html ``` ## Exemplos {#examples} ### Avatar com imagem {#example-src} Use o atributo `src` para definir um link de imagem como avatar, ou adicionar um elemento `` no slot padrão como avatar. ```html Exemplo de avatar com imagem

``` Use o atributo `fit` para definir como a imagem se ajusta ao contêiner, similar ao [`object-fit`](https://developer.mozilla.org/pt-BR/docs/Web/CSS/object-fit) nativo. ### Avatar com ícone {#example-icon} Use o atributo `icon` para definir um ícone do Material Icons como avatar, ou adicione um elemento de ícone no slot padrão. ```html

``` ### Avatar com caractere {#example-char} Use qualquer texto no slot padrão como avatar. ```html A ``` ## mdui-avatar API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Descrição
src	src	true	string	A URL da imagem do avatar.
fit	fit	true	'contain' \| 'cover' \| 'fill' \| 'none' \| 'scale-down'	Define como a imagem se ajusta ao contêiner, igual à propriedade nativa `object-fit`. Os valores possíveis são: `contain`: Mantém a proporção original da imagem; o conteúdo é dimensionado proporcionalmente. `cover`: Mantém a proporção original da imagem, mas parte do conteúdo pode ser cortada. `fill`: Valor padrão. Não mantém a proporção original; o conteúdo é esticado para preencher todo o contêiner. `none`: Mantém o tamanho original da imagem; o conteúdo não é dimensionado ou esticado. `scale-down`: Mantém a proporção original da imagem; o tamanho do conteúdo é o menor entre `none` e `contain`.
icon	icon	true	string	Nome do ícone Material Icons para o avatar.
label	label	true	string	Texto alternativo para o avatar.

### Slots

Nome	Descrição
(padrão)	Conteúdo personalizado do avatar. Pode ser letras, caracteres chineses, um elemento `<img>`, ícone, etc.

### CSS Parts

Nome	Descrição
image	Elemento `<img>` dentro do componente quando uma imagem é usada como avatar.
icon	Elemento `<mdui-icon>` dentro do componente quando um ícone é usado como avatar.

### Propriedades CSS personalizadas

Nome	Descrição
--shape-corner	Tamanho da borda arredondada do componente. Pode ser um valor em pixels, mas é recomendado usar os design tokens.

# Componente Badge O Badge exibe informações dinâmicas, como contagens ou indicadores de status. Pode conter texto ou números. ## Como usar {#usage} Importe o componente quando necessário: ```js import 'mdui/components/badge.js'; ``` Importe o tipo TypeScript do componente quando necessário: ```ts import type { Badge } from 'mdui/components/badge.js'; ``` Exemplo de uso: ```html 12 ``` ## Exemplos {#examples} ### Variante {#example-variant} Use o atributo `variant` para definir a variante do badge. Quando `variant` é `large`, um badge grande será exibido. Você também pode adicionar o texto a ser exibido no slot padrão. ```html 99+ ``` ## mdui-badge API ### Propriedades

Atributo Propriedade Reflect Tipo Padrão Descrição

variant

true

'small' | 'large'

'large'

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
variant	variant	true	'small' \| 'large'	'large'	Forma do badge. Os valores possíveis são: `small`: Badge pequeno, não exibe texto. `large`: Badge grande, exibe texto.

Forma do badge. Os valores possíveis são:

small: Badge pequeno, não exibe texto.
large: Badge grande, exibe texto.

### Slots

Nome	Descrição
(padrão)	Texto exibido no badge.

### Propriedades CSS personalizadas

Nome	Descrição
--shape-corner	Tamanho da borda arredondada do componente. Pode ser um valor em pixels, mas é recomendado usar os design tokens.

# Componente BottomAppBar A barra de aplicativo inferior exibe principalmente itens de navegação e outras operações importantes na parte inferior da página em dispositivos móveis. ## Como usar {#usage} Importe o componente quando necessário: ```js import 'mdui/components/bottom-app-bar.js'; ``` Importe o tipo TypeScript do componente quando necessário: ```ts import type { BottomAppBar } from 'mdui/components/bottom-app-bar.js'; ``` Exemplo de uso: (Nota: o `style="position: relative"` no exemplo é apenas para demonstração; remova ao usar em produção.) ```html

``` **Observações:** Este componente usa `position: fixed` por padrão e adiciona automaticamente `padding-bottom` ao `body` para evitar que o conteúdo da página seja ocultado pelo componente. No entanto, nos dois casos abaixo, ele usará `position: absolute` por padrão: 1. Quando o atributo `scroll-target` é especificado. Assim, `padding-bottom` será adicionado ao elemento `scroll-target`. 2. Quando está dentro do componente [``](/pt-br/docs/2/components/layout). Assim, nenhum `padding-bottom` será adicionado. ## Exemplos {#examples} ### Dentro de um contêiner especificado {#example-scroll-target} Por padrão, a barra de aplicativo inferior é exibida na parte inferior da página, relativa à janela atual. Para colocar a barra de aplicativo inferior dentro de um contêiner específico, defina o atributo `scroll-target` com o valor do seletor CSS ou elemento DOM do contêiner de conteúdo rolável. Assim, a barra de aplicativo inferior será exibida em relação ao elemento pai (você precisa adicionar os estilos `position: relative; overflow: hidden` ao elemento pai). ```html

Content

``` ### Ocultar ao rolar {#example-scroll-behavior} Defina o atributo `scroll-behavior` como `hide` para ocultar a barra de aplicativo inferior ao rolar a página para baixo e exibi-la ao rolar para cima. Use o atributo `scroll-threshold` para definir quantos pixels rolar antes de começar a ocultar a barra de aplicativo inferior. ```html

Content

``` ### Botão de ação flutuante fixo {#example-fab-detach} Se a barra de aplicativo inferior contém um [botão de ação flutuante](/pt-br/docs/2/components/fab), você pode adicionar o atributo `fab-detach` para que, ao rolar a página e a barra de aplicativo inferior for ocultada, o botão de ação flutuante permaneça no canto inferior direito da página. ```html

``` ## mdui-bottom-app-bar API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
hide	hide	true	boolean	false	Define se o componente está oculto.
fab-detach	fabDetach	true	boolean	false	Define se o componente `<mdui-fab>` deve ser desanexado da barra de aplicativo. Se `true`, quando a barra for ocultada, o `<mdui-fab>` ainda permanecerá na página.
scroll-behavior	scrollBehavior	true	'hide' \| 'shrink' \| 'elevate'		Comportamento de rolagem. O valor possível é: `hide`: Ocultar ao rolar.
scroll-target	scrollTarget	false	string \| HTMLElement \| JQ<HTMLElement>		O elemento no qual o evento de rolagem será monitorado. O valor pode ser um seletor CSS, um elemento DOM ou um objeto JQ. Por padrão, monitora o evento de rolagem da `window`.
scroll-threshold	scrollThreshold	true	number		A distância de rolagem, em `px`, necessária para acionar o comportamento.
order	order	true	number		A ordem de layout deste componente dentro do `<mdui-layout>`, em ordem crescente. O valor padrão é `0`.

### Eventos

Nome	Descrição
show	Disparado quando o componente começa a ser exibido. Pode impedir a exibição chamando `event.preventDefault()`.
shown	Disparado quando a animação de exibição é concluída.
hide	Disparado quando o componente começa a ser ocultado. Pode impedir a ocultação chamando `event.preventDefault()`.
hidden	Disparado quando a animação de ocultação é concluída.

### Slots

Nome	Descrição
(padrão)	Elementos dentro da barra de aplicativo inferior.

### Propriedades CSS personalizadas

Nome	Descrição
--shape-corner	Tamanho da borda arredondada do componente. Pode ser um valor em pixels, mas é recomendado usar os design tokens.
--z-index	Valor CSS `z-index` do componente.

# 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 Button ``` ## Exemplos {#examples} ### Forma {#example-variant} Use o atributo `variant` para definir a forma do botão. ```html Elevated

Filled

Tonal

Outlined

Text ``` ### Largura total {#example-full-width} Use o atributo `full-width` para fazer o botão ocupar toda a largura do elemento pai. ```html 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 Icon Slot

``` ### 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 Link ``` ### 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 Disabled

Loading & Disabled ``` ## mdui-button API ### Propriedades

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

### Métodos

Nome	Descrição
click(): void	Simula um clique do mouse no elemento.
focus(options?: FocusOptions): void	Define o foco no elemento atual. Você pode passar um objeto como argumento, com as seguintes propriedades: `preventScroll`: 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 `true`.
blur(): void	Remove o foco do elemento atual.
checkValidity(): boolean	Verifica se o campo do formulário passou na validação. Se não passou, retorna `false` e dispara o evento `invalid`; se passou, retorna `true`.
reportValidity(): boolean	Verifica se o campo do formulário passou na validação. Se não passou, retorna `false` e dispara o evento `invalid`; se passou, retorna `true`. Se a validação falhar, também exibe uma mensagem de erro no componente.
setCustomValidity(message: string): void	Define um texto de erro personalizado. Enquanto este texto não estiver vazio, indica que o campo não passou na validação.

### Eventos

Nome	Descrição
focus	Disparado ao receber foco.
blur	Disparado ao perder o foco.
invalid	Disparado quando a validação do campo do formulário falha.

### Slots

Nome	Descrição
(padrão)	Texto do botão.
icon	Elemento à esquerda do botão.
end-icon	Elemento à direita do botão.

### CSS Parts

Nome	Descrição
button	Elemento `<button>` ou `<a>` interno.
label	Texto do botão.
icon	Ícone à esquerda do botão.
end-icon	Ícone à direita do botão.
loading	Elemento `<mdui-circular-progress>` no estado de carregamento.

### Propriedades CSS personalizadas

Nome	Descrição
--shape-corner	Tamanho da borda arredondada do componente. Pode ser um valor em pixels, mas é recomendado usar os design tokens.

# Componente ButtonIcon O botão de ícone é usado principalmente para ações secundárias. ## Como usar {#usage} Importe o componente quando necessário: ```js import 'mdui/components/button-icon.js'; ``` Importe o tipo TypeScript do componente quando necessário: ```ts import type { ButtonIcon } from 'mdui/components/button-icon.js'; ``` Exemplo de uso: ```html ``` ## Exemplos {#examples} ### Ícone {#example-icon} Use o atributo `icon` para definir o nome do ícone do Material Icons. Você também pode adicionar um elemento de ícone pelo slot padrão. ```html

``` ### Forma {#example-variant} Use o atributo `variant` para definir a forma do botão de ícone. ```html

``` ### Selecionável {#example-selectable} Use o atributo `selectable` para tornar o botão de ícone selecionável. ```html ``` Use o atributo `selected-icon` para definir o nome do ícone do Material Icons no estado selecionado. Você também pode adicionar o elemento de ícone do estado selecionado pelo slot `selected-icon`. ```html

``` Quando o botão de ícone é selecionado, o atributo `selected` torna-se `true`. Você também pode adicionar o atributo `selected` para que o botão de ícone inicie no estado selecionado. ```html ``` ### Link {#example-link} Use o atributo `href` para transformar o botão de ícone em um link. Assim, você também pode usar os atributos relacionados a links: `download`, `target`, `rel`. ```html ``` ### Estado desabilitado e carregando {#example-disabled} Use o atributo `disabled` para desabilitar o botão de ícone; adicione o atributo `loading` para adicionar um estado de carregamento ao botão de ícone. ```html

``` ## mdui-button-icon API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
variant	variant	true	'standard' \| 'filled' \| 'tonal' \| 'outlined'	'standard'	Forma do botão de ícone. Os valores possíveis são: `standard`: Adequado para ações de prioridade mais baixa. `filled`: Efeito visual forte, adequado para ações de alta prioridade. `tonal`: Efeito visual entre `filled` e `outlined`, adequado para ações de prioridade média-alta. `outlined`: Adequado para ações de prioridade média.
icon	icon	true	string		Nome do ícone Material Icons. Também pode ser definido via slot padrão.
selected-icon	selectedIcon	true	string		Nome do ícone Material Icons para o estado selecionado. Também pode ser definido via `slot="selected-icon"`.
selectable	selectable	true	boolean	false	Define se o componente é selecionável.
selected	selected	true	boolean	false	Define se o componente está selecionado.
href	href	true	string		A URL de destino do link. Ao definir esta propriedade, o componente será renderizado internamente como um elemento `<a>` e poderá usar atributos de link.
download	download	true	string		O nome do arquivo para download. Nota: Esta propriedade só é válida quando o atributo `href` está definido.
target	target	true	'_blank' \| '_parent' \| '_self' \| '_top'		Define como o link será aberto. Os valores possíveis são: `_blank`: Abre o link em uma nova janela `_parent`: Abre o link no frame pai `_self`: Padrão. Abre o link no frame atual `_top`: Abre o link na janela inteira Nota: Esta propriedade só é válida quando o atributo `href` está definido.
rel	rel	true	'alternate' \| 'author' \| 'bookmark' \| 'external' \| 'help' \| 'license' \| 'me' \| 'next' \| 'nofollow' \| 'noreferrer' \| 'opener' \| 'prev' \| 'search' \| 'tag'		A relação entre o documento atual e o documento vinculado. Os valores possíveis são: `alternate`: Versão alternativa do documento atual `author`: Autor do documento atual ou artigo `bookmark`: Link permanente para a seção ancestral mais próxima `external`: O documento referenciado não está no mesmo site do documento atual `help`: Link para documentação de ajuda relacionada `license`: O conteúdo principal do documento atual está coberto pela licença de direitos autorais do arquivo referenciado `me`: O documento atual representa o proprietário do conteúdo vinculado `next`: O documento atual faz parte de uma série, e o documento referenciado é o próximo da série `nofollow`: O autor ou editor do documento atual não endossa o arquivo referenciado `noreferrer`: Não inclui o cabeçalho `Referer`. Tem efeito semelhante ao `noopener` `opener`: Se o hiperlink criar um contexto de navegação de nível superior (ou seja, o valor do atributo `target` for `_blank`), cria um contexto de navegação auxiliar `prev`: O documento atual faz parte de uma série, e o documento referenciado é o anterior da série `search`: Fornece um link para um recurso que pode ser usado para pesquisar o arquivo atual e suas páginas relacionadas `tag`: Fornece uma tag (identificada pelo endereço fornecido) aplicável ao documento atual Nota: Disponível apenas quando o atributo `href` é especificado.
autofocus	autofocus	true	boolean	false	Define se o elemento deve receber foco automaticamente após o carregamento da página.
tabindex	tabIndex	false	number		A ordem do elemento ao navegar com a tecla Tab.
disabled	disabled	true	boolean	false	Define se o componente está desabilitado.
loading	loading	true	boolean	false	Define se o componente está em estado de carregamento.
name	name	true	string	''	O nome do botão, que será enviado com os dados do formulário. Nota: Esta propriedade só é válida quando o atributo `href` não está definido.
value	value	true	string	''	O valor inicial do botão, que será enviado com os dados do formulário. Nota: Esta propriedade só é válida quando o atributo `href` não está definido.
type	type	true	'submit' \| 'reset' \| 'button'	'button'	O tipo do botão. O tipo padrão é `button`. Os tipos possíveis são: `submit`: Clicar no botão envia os dados do formulário para o servidor `reset`: Clicar no botão redefine todos os campos do formulário para seus valores iniciais `button`: Este tipo de botão não tem comportamento padrão Nota: Esta propriedade só é válida quando o atributo `href` não é especificado.
form	form	true	string		O elemento `<form>` associado. O valor deste atributo deve ser o `id` de um elemento `<form>` na mesma página. Se este atributo não for especificado, o elemento precisa ser um elemento filho de um `<form>`. Com este atributo, você pode colocar o elemento em qualquer lugar da página, não apenas como filho do elemento `<form>`. Nota: Esta propriedade só é válida quando o atributo `href` não é especificado.
formaction	formAction	true	string		Especifica a URL para envio do formulário. Se este atributo for especificado, ele substituirá o atributo `action` do elemento `<form>`. Nota: Esta propriedade só é válida quando o atributo `href` não é especificado e `type="submit"`.
formenctype	formEnctype	true	'application/x-www-form-urlencoded' \| 'multipart/form-data' \| 'text/plain'		Especifica o tipo de conteúdo ao enviar o formulário para o servidor. Os valores possíveis são: `application/x-www-form-urlencoded`: Valor padrão quando o atributo não é especificado `multipart/form-data`: Usado quando o formulário contém um elemento `<input type="file">` `text/plain`: Novo no HTML5, usado para depuração Se este atributo for especificado, ele substituirá o atributo `enctype` do elemento `<form>`. Nota: Esta propriedade só é válida quando o atributo `href` não é especificado e `type="submit"`.
formmethod	formMethod	true	'post' \| 'get'		Especifica o método HTTP a ser usado ao enviar o formulário. Os valores possíveis são: `post`: Os dados do formulário são incluídos no corpo do formulário e enviados ao servidor `get`: Os dados do formulário são anexados à URI do formulário com `?` 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 Se este atributo for definido, ele substituirá o atributo `method` do elemento `<form>`. Nota: Esta propriedade só é válida quando o atributo `href` não é definido e `type="submit"`.
formnovalidate	formNoValidate	true	boolean	false	Se este atributo for definido, a validação do formulário não será executada ao enviar. Se este atributo for definido, ele substituirá o atributo `novalidate` do elemento `<form>`. Nota: Esta propriedade só é válida quando o atributo `href` não é definido e `type="submit"`.
formtarget	formTarget	true	'_self' \| '_blank' \| '_parent' \| '_top'		Onde exibir a resposta recebida após o envio do formulário. Os valores possíveis são: `_self`: Opção padrão, abre no frame atual `_blank`: Abre em uma nova janela `_parent`: Abre no frame pai `_top`: Abre na janela inteira Se este atributo for definido, ele substituirá o atributo `target` do elemento `<form>`. Nota: Esta propriedade só é válida quando o atributo `href` não é definido e `type="submit"`.
undefined	validity	false	ValidityState		Objeto que representa o estado de validação do formulário. Consulte `ValidityState` para mais detalhes.
undefined	validationMessage	false	string		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.

### Métodos

Nome	Descrição
click(): void	Simula um clique do mouse no elemento.
focus(options?: FocusOptions): void	Define o foco no elemento atual. Você pode passar um objeto como argumento, com as seguintes propriedades: `preventScroll`: 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 `true`.
blur(): void	Remove o foco do elemento atual.
checkValidity(): boolean	Verifica se o campo do formulário passou na validação. Se não passou, retorna `false` e dispara o evento `invalid`; se passou, retorna `true`.
reportValidity(): boolean	Verifica se o campo do formulário passou na validação. Se não passou, retorna `false` e dispara o evento `invalid`; se passou, retorna `true`. Se a validação falhar, também exibe uma mensagem de erro no componente.
setCustomValidity(message: string): void	Define um texto de erro personalizado. Enquanto este texto não estiver vazio, indica que o campo não passou na validação.

### Eventos

Nome	Descrição
focus	Disparado ao receber foco.
blur	Disparado ao perder o foco.
change	Disparado quando o estado de seleção muda.
invalid	Disparado quando a validação do campo do formulário falha.

### Slots

Nome	Descrição
(padrão)	Componente de ícone.
selected-icon	Elemento de ícone exibido no estado selecionado.

### CSS Parts

Nome	Descrição
button	Elemento `<button>` ou `<a>` interno.
icon	Ícone no estado não selecionado.
selected-icon	Ícone no estado selecionado.
loading	Elemento `<mdui-circular-progress>` no estado de carregamento.

### Propriedades CSS personalizadas

Nome	Descrição
--shape-corner	Tamanho da borda arredondada do componente. Pode ser um valor em pixels, mas é recomendado usar os design tokens.

# Componente Card O Card é um componente versátil que contém conteúdo e ações relacionadas a um único tópico. ## Como usar {#usage} Importe o componente quando necessário: ```js import 'mdui/components/card.js'; ``` Importe o tipo TypeScript do componente quando necessário: ```ts import type { Card } from 'mdui/components/card.js'; ``` Exemplo de uso: ```html Card ``` ## Exemplos {#examples} ### Forma {#example-variant} Use o atributo `variant` para definir a forma do card. ```html

``` ### Clicável {#example-clickable} Use o atributo `clickable` para tornar o card clicável. Isso adicionará um efeito de hover e ondulação ao clicar. ```html ``` ### Link {#example-link} Use o atributo `href` para transformar o card em um link. Assim, você também pode usar os atributos relacionados a links: `download`, `target`, `rel`. ```html ``` ### Estado desabilitado {#example-disabled} Use o atributo `disabled` para desabilitar o card. ```html ``` ## mdui-card API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
variant	variant	true	'elevated' \| 'filled' \| 'outlined'	'elevated'	Forma do card. Os valores possíveis são: `elevated`: Card com sombra, com maior separação visual do fundo. `filled`: Card com cor de fundo, com menor separação visual do fundo. `outlined`: Card com borda, com maior separação visual do fundo.
clickable	clickable	true	boolean	false	Define se o card é clicável. Quando `true`, o card terá efeitos visuais ao passar o mouse e uma ondulação ao clicar.
disabled	disabled	true	boolean	false	Define se o componente está desabilitado.
href	href	true	string		A URL de destino do link. Ao definir esta propriedade, o componente será renderizado internamente como um elemento `<a>` e poderá usar atributos de link.
download	download	true	string		O nome do arquivo para download. Nota: Esta propriedade só é válida quando o atributo `href` está definido.
target	target	true	'_blank' \| '_parent' \| '_self' \| '_top'		Define como o link será aberto. Os valores possíveis são: `_blank`: Abre o link em uma nova janela `_parent`: Abre o link no frame pai `_self`: Padrão. Abre o link no frame atual `_top`: Abre o link na janela inteira Nota: Esta propriedade só é válida quando o atributo `href` está definido.
rel	rel	true	'alternate' \| 'author' \| 'bookmark' \| 'external' \| 'help' \| 'license' \| 'me' \| 'next' \| 'nofollow' \| 'noreferrer' \| 'opener' \| 'prev' \| 'search' \| 'tag'		A relação entre o documento atual e o documento vinculado. Os valores possíveis são: `alternate`: Versão alternativa do documento atual `author`: Autor do documento atual ou artigo `bookmark`: Link permanente para a seção ancestral mais próxima `external`: O documento referenciado não está no mesmo site do documento atual `help`: Link para documentação de ajuda relacionada `license`: O conteúdo principal do documento atual está coberto pela licença de direitos autorais do arquivo referenciado `me`: O documento atual representa o proprietário do conteúdo vinculado `next`: O documento atual faz parte de uma série, e o documento referenciado é o próximo da série `nofollow`: O autor ou editor do documento atual não endossa o arquivo referenciado `noreferrer`: Não inclui o cabeçalho `Referer`. Tem efeito semelhante ao `noopener` `opener`: Se o hiperlink criar um contexto de navegação de nível superior (ou seja, o valor do atributo `target` for `_blank`), cria um contexto de navegação auxiliar `prev`: O documento atual faz parte de uma série, e o documento referenciado é o anterior da série `search`: Fornece um link para um recurso que pode ser usado para pesquisar o arquivo atual e suas páginas relacionadas `tag`: Fornece uma tag (identificada pelo endereço fornecido) aplicável ao documento atual Nota: Disponível apenas quando o atributo `href` é especificado.
autofocus	autofocus	true	boolean	false	Define se o elemento deve receber foco automaticamente após o carregamento da página.
tabindex	tabIndex	false	number		A ordem do elemento ao navegar com a tecla Tab.

### Métodos

Nome Descrição

click(): void

Simula um clique do mouse no elemento.

focus(options?: FocusOptions): void

Define o foco no elemento atual.

Você pode passar um objeto como argumento, com as seguintes propriedades:

preventScroll: 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 true.

blur(): void

Remove o foco do elemento atual.

### Eventos

Nome	Descrição
focus	Disparado ao receber foco.
blur	Disparado ao perder o foco.

### Slots

Nome	Descrição
(padrão)	Conteúdo do card.

### Propriedades CSS personalizadas

Nome	Descrição
--shape-corner	Tamanho da borda arredondada do componente. Pode ser um valor em pixels, mas é recomendado usar os design tokens.

# Componente Checkbox O Checkbox permite que os usuários selecionem uma ou mais opções de um conjunto, ou alternem o estado ligado/desligado de uma única opção. ## Como usar {#usage} Importe o componente quando necessário: ```js import 'mdui/components/checkbox.js'; ``` Importe o tipo TypeScript do componente quando necessário: ```ts import type { Checkbox } from 'mdui/components/checkbox.js'; ``` Exemplo de uso: ```html Checkbox ``` ## Exemplos {#examples} ### Estado selecionado {#example-checked} Quando o checkbox está selecionado, o valor do atributo `checked` é `true`. Use o atributo `checked` para iniciar o checkbox no estado selecionado. ```html Checkbox ``` ### Estado desabilitado {#example-disabled} Use o atributo `disabled` para desabilitar o checkbox. ```html Checkbox Checkbox ``` ### Estado indeterminado {#example-indeterminate} Use o atributo `indeterminate` para que o checkbox fique no estado indeterminado. ```html Checkbox ``` ### Ícone {#example-icon} Defina os atributos `unchecked-icon`, `checked-icon` e `indeterminate-icon` para definir os ícones do Material Icons nos estados não selecionado, selecionado e indeterminado, respectivamente. Você também pode defini-los pelos slots `unchecked-icon`, `checked-icon` e `indeterminate-icon`. ```html Checkbox

Checkbox

Checkbox ``` ## mdui-checkbox API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
disabled	disabled	true	boolean	false	Define se o componente está desabilitado.
checked	checked	true	boolean	false	Define se o componente está selecionado.
undefined	defaultChecked	false	boolean	false	Estado de seleção padrão. Ao redefinir o formulário, será restaurado para este estado. Esta propriedade só pode ser definida via propriedade JavaScript.
indeterminate	indeterminate	true	boolean	false	Define se o componente está no estado indeterminado.
required	required	true	boolean	false	Define se, ao enviar o formulário, é obrigatório que esta caixa de seleção esteja selecionada.
form	form	true	string		O elemento `<form>` associado. O valor deste atributo deve ser o `id` de um elemento `<form>` na mesma página. Se este atributo não for especificado, o elemento precisa ser um elemento filho de um `<form>`. Com este atributo, você pode colocar o elemento em qualquer lugar da página, não apenas como filho do elemento `<form>`.
name	name	true	string	''	Nome da caixa de seleção, que será enviado com os dados do formulário.
value	value	true	string	'on'	Valor da caixa de seleção, que será enviado com os dados do formulário.
unchecked-icon	uncheckedIcon	true	string		Nome do ícone Material Icons para o estado não selecionado. Também pode ser definido via `slot="unchecked-icon"`.
checked-icon	checkedIcon	true	string		Nome do ícone Material Icons para o estado selecionado. Também pode ser definido via `slot="checked-icon"`.
indeterminate-icon	indeterminateIcon	true	string		Nome do ícone Material Icons para o estado indeterminado. Também pode ser definido via `slot="indeterminate-icon"`.
undefined	validity	false	ValidityState		Objeto que representa o estado de validação do formulário. Consulte `ValidityState` para mais detalhes.
undefined	validationMessage	false	string		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.
autofocus	autofocus	true	boolean	false	Define se o elemento deve receber foco automaticamente após o carregamento da página.
tabindex	tabIndex	false	number		A ordem do elemento ao navegar com a tecla Tab.

### Métodos

Nome	Descrição
checkValidity(): boolean	Verifica se o campo do formulário passou na validação. Se não passou, retorna `false` e dispara o evento `invalid`; se passou, retorna `true`.
reportValidity(): boolean	Verifica se o campo do formulário passou na validação. Se não passou, retorna `false` e dispara o evento `invalid`; se passou, retorna `true`. Se a validação falhar, também exibe uma mensagem de erro no componente.
setCustomValidity(message: string): void	Define um texto de erro personalizado. Enquanto este texto não estiver vazio, indica que o campo não passou na validação.
click(): void	Simula um clique do mouse no elemento.
focus(options?: FocusOptions): void	Define o foco no elemento atual. Você pode passar um objeto como argumento, com as seguintes propriedades: `preventScroll`: 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 `true`.
blur(): void	Remove o foco do elemento atual.

### Eventos

Nome	Descrição
focus	Disparado ao receber foco.
blur	Disparado ao perder o foco.
change	Disparado quando o estado de seleção muda.
input	Disparado quando o estado de seleção muda.
invalid	Disparado quando a validação do campo do formulário falha.

### Slots

Nome	Descrição
(padrão)	Texto da caixa de seleção.
unchecked-icon	Ícone do estado não selecionado.
checked-icon	Ícone do estado selecionado.
indeterminate-icon	Ícone do estado indeterminado.

### CSS Parts

Nome	Descrição
control	Contêiner do ícone esquerdo.
unchecked-icon	Ícone do estado não selecionado.
checked-icon	Ícone do estado selecionado.
indeterminate-icon	Ícone do estado indeterminado.
label	Texto da caixa de seleção.

# Componente Chip O Chip ajuda os usuários a inserir informações, fazer seleções, filtrar conteúdo ou realizar ações. ## Como usar {#usage} Importe o componente quando necessário: ```js import 'mdui/components/chip.js'; ``` Importe o tipo TypeScript do componente quando necessário: ```ts import type { Chip } from 'mdui/components/chip.js'; ``` Exemplo de uso: ```html Chip ``` ## Exemplos {#examples} ### Forma {#example-variant} Use o atributo `variant` para definir a forma do chip. Existem 4 tipos de chip, escolha de acordo com a finalidade: - `assist`: Exibe ações auxiliares relacionadas ao contexto atual. Exemplo: em uma página de pedidos, disponibilizar funções como compartilhar, favoritar etc. - `filter`: Filtra conteúdo. Exemplo: em uma página de resultados de busca, filtrar os resultados. - `input`: Representa fragmentos de informação inseridos pelo usuário. Exemplo: contatos no campo "Para" do Gmail. - `suggestion`: Oferece informações de recomendação geradas dinamicamente para simplificar as ações do usuário. Exemplo, em um aplicativo de chat, sugerir mensagens que o usuário possa querer enviar. ```html Assist

Filter

Input

Suggestion ``` ### Sombra {#example-elevated} Use o atributo `elevated` para dar sombra ao chip. ```html Chip ``` ### Ícone {#example-icon} Adicione os atributos `icon` e `end-icon` para adicionar ícones do Material Icons à esquerda e à direita do chip, respectivamente. Você também pode adicionar elementos pelos slots `icon` e `end-icon`. ```html Icon

End Icon

Slot

``` ### Link {#example-link} Use o atributo `href` para transformar o chip em um link. Assim, você também pode usar os atributos relacionados a links: `download`, `target`, `rel`. ```html Link ``` ### Estado desabilitado e carregando {#example-disabled} Use o atributo `disabled` para desabilitar o chip; adicione o atributo `loading` para adicionar um estado de carregamento ao chip. ```html Disabled

Loading & Disabled ``` ### Selecionável {#example-selectable} Use o atributo `selectable` para tornar o chip selecionável. ```html Chip ``` Use o atributo `selected-icon` para definir o nome do ícone do Material Icons no estado selecionado. Você também pode adicionar o elemento de ícone do estado selecionado pelo slot `selected-icon`. ```html Chip Chip ``` Quando o chip é selecionado, o atributo `selected` torna-se `true`. Você também pode adicionar o atributo `selected` para que o chip inicie no estado selecionado. ```html Chip ``` ### Deletável {#example-deletable} Use o atributo `deletable` para que um ícone de deletar apareça no lado direito do chip. Clicar neste ícone dispara o evento `delete`. Use o atributo `delete-icon` para definir o nome do ícone do Material Icons para deletar, ou o slot `delete-icon` para definir o elemento do ícone. ```html Chip

Chip

Chip ``` ## mdui-chip API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
variant	variant	true	'assist' \| 'filter' \| 'input' \| 'suggestion'	'assist'	Forma do chip. Os valores possíveis são: `assist`: Usado para exibir ações auxiliares relacionadas ao contexto atual, como compartilhar ou favoritar em uma página de pedidos. `filter`: Usado para filtrar conteúdo, como filtrar resultados de pesquisa em uma página de resultados. `input`: Usado para representar fragmentos de informação inseridos pelo usuário, como contatos no campo "Para" do Gmail. `suggestion`: Usado para fornecer recomendações geradas dinamicamente para simplificar a ação do usuário, como prever mensagens que o usuário pode querer enviar em um aplicativo de chat.
elevated	elevated	true	boolean	false	Define se o componente deve exibir sombra.
selectable	selectable	true	boolean	false	Define se o componente é selecionável.
selected	selected	true	boolean	false	Define se o componente está selecionado.
deletable	deletable	true	boolean	false	Define se o componente é removível. Quando `true`, um ícone de remoção é exibido à direita do chip.
icon	icon	true	string		Nome do ícone Material Icons à esquerda. Também pode ser definido via `slot="icon"`.
selected-icon	selectedIcon	true	string		Nome do ícone Material Icons à esquerda no estado selecionado. Também pode ser definido via `slot="selected-icon"`.
end-icon	endIcon	true	string		Nome do ícone Material Icons à direita. Também pode ser definido via `slot="end-icon"`.
delete-icon	deleteIcon	true	string		Nome do ícone Material Icons para o ícone de remoção à direita quando removível. Também pode ser definido via `slot="delete-icon"`.
href	href	true	string		A URL de destino do link. Ao definir esta propriedade, o componente será renderizado internamente como um elemento `<a>` e poderá usar atributos de link.
download	download	true	string		O nome do arquivo para download. Nota: Esta propriedade só é válida quando o atributo `href` está definido.
target	target	true	'_blank' \| '_parent' \| '_self' \| '_top'		Define como o link será aberto. Os valores possíveis são: `_blank`: Abre o link em uma nova janela `_parent`: Abre o link no frame pai `_self`: Padrão. Abre o link no frame atual `_top`: Abre o link na janela inteira Nota: Esta propriedade só é válida quando o atributo `href` está definido.
rel	rel	true	'alternate' \| 'author' \| 'bookmark' \| 'external' \| 'help' \| 'license' \| 'me' \| 'next' \| 'nofollow' \| 'noreferrer' \| 'opener' \| 'prev' \| 'search' \| 'tag'		A relação entre o documento atual e o documento vinculado. Os valores possíveis são: `alternate`: Versão alternativa do documento atual `author`: Autor do documento atual ou artigo `bookmark`: Link permanente para a seção ancestral mais próxima `external`: O documento referenciado não está no mesmo site do documento atual `help`: Link para documentação de ajuda relacionada `license`: O conteúdo principal do documento atual está coberto pela licença de direitos autorais do arquivo referenciado `me`: O documento atual representa o proprietário do conteúdo vinculado `next`: O documento atual faz parte de uma série, e o documento referenciado é o próximo da série `nofollow`: O autor ou editor do documento atual não endossa o arquivo referenciado `noreferrer`: Não inclui o cabeçalho `Referer`. Tem efeito semelhante ao `noopener` `opener`: Se o hiperlink criar um contexto de navegação de nível superior (ou seja, o valor do atributo `target` for `_blank`), cria um contexto de navegação auxiliar `prev`: O documento atual faz parte de uma série, e o documento referenciado é o anterior da série `search`: Fornece um link para um recurso que pode ser usado para pesquisar o arquivo atual e suas páginas relacionadas `tag`: Fornece uma tag (identificada pelo endereço fornecido) aplicável ao documento atual Nota: Disponível apenas quando o atributo `href` é especificado.
autofocus	autofocus	true	boolean	false	Define se o elemento deve receber foco automaticamente após o carregamento da página.
tabindex	tabIndex	false	number		A ordem do elemento ao navegar com a tecla Tab.
disabled	disabled	true	boolean	false	Define se o componente está desabilitado.
loading	loading	true	boolean	false	Define se o componente está em estado de carregamento.
name	name	true	string	''	O nome do botão, que será enviado com os dados do formulário. Nota: Esta propriedade só é válida quando o atributo `href` não está definido.
value	value	true	string	''	O valor inicial do botão, que será enviado com os dados do formulário. Nota: Esta propriedade só é válida quando o atributo `href` não está definido.
type	type	true	'submit' \| 'reset' \| 'button'	'button'	O tipo do botão. O tipo padrão é `button`. Os tipos possíveis são: `submit`: Clicar no botão envia os dados do formulário para o servidor `reset`: Clicar no botão redefine todos os campos do formulário para seus valores iniciais `button`: Este tipo de botão não tem comportamento padrão Nota: Esta propriedade só é válida quando o atributo `href` não é especificado.
form	form	true	string		O elemento `<form>` associado. O valor deste atributo deve ser o `id` de um elemento `<form>` na mesma página. Se este atributo não for especificado, o elemento precisa ser um elemento filho de um `<form>`. Com este atributo, você pode colocar o elemento em qualquer lugar da página, não apenas como filho do elemento `<form>`. Nota: Esta propriedade só é válida quando o atributo `href` não é especificado.
formaction	formAction	true	string		Especifica a URL para envio do formulário. Se este atributo for especificado, ele substituirá o atributo `action` do elemento `<form>`. Nota: Esta propriedade só é válida quando o atributo `href` não é especificado e `type="submit"`.
formenctype	formEnctype	true	'application/x-www-form-urlencoded' \| 'multipart/form-data' \| 'text/plain'		Especifica o tipo de conteúdo ao enviar o formulário para o servidor. Os valores possíveis são: `application/x-www-form-urlencoded`: Valor padrão quando o atributo não é especificado `multipart/form-data`: Usado quando o formulário contém um elemento `<input type="file">` `text/plain`: Novo no HTML5, usado para depuração Se este atributo for especificado, ele substituirá o atributo `enctype` do elemento `<form>`. Nota: Esta propriedade só é válida quando o atributo `href` não é especificado e `type="submit"`.
formmethod	formMethod	true	'post' \| 'get'		Especifica o método HTTP a ser usado ao enviar o formulário. Os valores possíveis são: `post`: Os dados do formulário são incluídos no corpo do formulário e enviados ao servidor `get`: Os dados do formulário são anexados à URI do formulário com `?` 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 Se este atributo for definido, ele substituirá o atributo `method` do elemento `<form>`. Nota: Esta propriedade só é válida quando o atributo `href` não é definido e `type="submit"`.
formnovalidate	formNoValidate	true	boolean	false	Se este atributo for definido, a validação do formulário não será executada ao enviar. Se este atributo for definido, ele substituirá o atributo `novalidate` do elemento `<form>`. Nota: Esta propriedade só é válida quando o atributo `href` não é definido e `type="submit"`.
formtarget	formTarget	true	'_self' \| '_blank' \| '_parent' \| '_top'		Onde exibir a resposta recebida após o envio do formulário. Os valores possíveis são: `_self`: Opção padrão, abre no frame atual `_blank`: Abre em uma nova janela `_parent`: Abre no frame pai `_top`: Abre na janela inteira Se este atributo for definido, ele substituirá o atributo `target` do elemento `<form>`. Nota: Esta propriedade só é válida quando o atributo `href` não é definido e `type="submit"`.
undefined	validity	false	ValidityState		Objeto que representa o estado de validação do formulário. Consulte `ValidityState` para mais detalhes.
undefined	validationMessage	false	string		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.

### Métodos

Nome	Descrição
click(): void	Simula um clique do mouse no elemento.
focus(options?: FocusOptions): void	Define o foco no elemento atual. Você pode passar um objeto como argumento, com as seguintes propriedades: `preventScroll`: 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 `true`.
blur(): void	Remove o foco do elemento atual.
checkValidity(): boolean	Verifica se o campo do formulário passou na validação. Se não passou, retorna `false` e dispara o evento `invalid`; se passou, retorna `true`.
reportValidity(): boolean	Verifica se o campo do formulário passou na validação. Se não passou, retorna `false` e dispara o evento `invalid`; se passou, retorna `true`. Se a validação falhar, também exibe uma mensagem de erro no componente.
setCustomValidity(message: string): void	Define um texto de erro personalizado. Enquanto este texto não estiver vazio, indica que o campo não passou na validação.

### Eventos

Nome	Descrição
focus	Disparado ao receber foco.
blur	Disparado ao perder o foco.
invalid	Disparado quando a validação do campo do formulário falha.
change	Disparado quando o estado de seleção muda.
delete	Disparado ao clicar no ícone de remoção.

### Slots

Nome	Descrição
(padrão)	Texto do chip.
icon	Elemento à esquerda.
end-icon	Elemento à direita.
selected-icon	Elemento à esquerda no estado selecionado.
delete-icon	Elemento de remoção à direita quando removível.

### CSS Parts

Nome	Descrição
button	Elemento `<button>` ou `<a>` interno.
label	Texto do chip.
icon	Ícone à esquerda.
end-icon	Ícone à direita.
selected-icon	Ícone à esquerda no estado selecionado.
delete-icon	Ícone de remoção à direita quando removível.
loading	Elemento `<mdui-circular-progress>` no estado de carregamento.

### Propriedades CSS personalizadas

Nome	Descrição
--shape-corner	Tamanho da borda arredondada do componente. Pode ser um valor em pixels, mas é recomendado usar os design tokens.

# Componente CircularProgress O indicador de progresso circular exibe o andamento de uma tarefa, como carregamento de dados ou envio de formulário. ## Como usar {#usage} Importe o componente quando necessário: ```js import 'mdui/components/circular-progress.js'; ``` Importe o tipo TypeScript do componente quando necessário: ```ts import type { CircularProgress } from 'mdui/components/circular-progress.js'; ``` Exemplo de uso: ```html ``` ## Exemplos {#examples} ### Progresso determinado {#example-value} O indicador de progresso circular por padrão é indeterminado. Use o atributo `value` para definir o progresso atual, onde o valor máximo padrão é `1`. ```html ``` Use o atributo `max` para definir o valor máximo do progresso. ```html ``` ## mdui-circular-progress API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
max	max	true	number	1	O valor máximo do indicador de progresso. O padrão é `1`.
value	value	false	number		O valor atual do indicador de progresso. Se não for especificado, exibe o estado indeterminado.

# Componente Collapse O componente collapse agrupa e oculta áreas de conteúdo complexas, mantendo a página organizada. Observe que o componente collapse por si só não possui nenhum estilo; você precisa adicionar estilos manualmente ou usá-lo com outros componentes. ## Como usar {#usage} Importe os componentes quando necessário: ```js import 'mdui/components/collapse.js'; import 'mdui/components/collapse-item.js'; ``` Importe os tipos TypeScript dos componentes quando necessário: ```ts import type { Collapse } from 'mdui/components/collapse.js'; import type { CollapseItem } from 'mdui/components/collapse-item.js'; ``` Exemplo de uso: ```html

first content

second content

``` ## Exemplos {#examples} ### Título e conteúdo do painel {#example-header} Use o atributo `header` do componente `` para definir o texto do cabeçalho do painel, ou use o slot `header` para definir o elemento do cabeçalho. O slot padrão do componente é usado para o conteúdo do painel. ```html

Item 1

Item 1 - subitem

Item 2

Item 2 - subitem

``` ### Modo acordeão {#example-accordion} Use o atributo `accordion` no componente `` para ativar o modo acordeão, onde apenas um painel pode ficar aberto por vez. ```html

Item 1

Item 1 - subitem

Item 2

Item 2 - subitem

``` ### Definir painéis ativos {#example-value} Através do atributo `value` do componente ``, você pode obter o painel atualmente aberto ou definir qual painel deve ser aberto. No modo acordeão, o valor do atributo `value` é uma string; você pode operar este atributo usando atributos HTML ou propriedades JavaScript. No modo não acordeão, o valor do atributo `value` é um array, e só pode ser operado por propriedades JavaScript. ```html

Modo acordeão

Item 1

Item 1 - subitem

Item 2

Item 2 - subitem

Modo não acordeão

Item 1

Item 1 - subitem

Item 2

Item 2 - subitem

``` ### Estado desabilitado {#example-disabled} Adicionando o atributo `disabled` ao componente ``, você pode desabilitar todo o grupo de collapse. Da mesma forma, adicionando o atributo `disabled` ao componente ``, você pode desabilitar um painel específico. ```html

Desabilitar todos

Item 1

Item 1 - subitem

Item 2

Item 2 - subitem

Desabilitar o primeiro painel

Item 1

Item 1 - subitem

Item 2

Item 2 - subitem

``` ### Elemento que aciona o collapse {#example-trigger} Por padrão, clicar em toda a área do cabeçalho do painel aciona o collapse. Você pode definir o atributo `trigger` do componente `` para definir o elemento que aciona o collapse. O atributo `trigger` pode ser um seletor CSS ou um elemento DOM. ```html

Item 1

Item 1 - subitem

``` ## mdui-collapse-item API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
value	value	true	string		O valor deste item de painel expansível.
header	header	true	string		O texto do cabeçalho deste item de painel expansível.
disabled	disabled	true	boolean	false	Define se este item de painel expansível está desabilitado.
trigger	trigger	false	string \| HTMLElement \| JQ<HTMLElement>		O elemento que, ao ser clicado, aciona a expansão/recolhimento. O valor pode ser um seletor CSS, um elemento DOM ou um objeto JQ. Por padrão, o clique em toda a área do cabeçalho aciona a ação.

### Eventos

Nome	Descrição
open	Disparado quando o componente começa a abrir.
opened	Disparado quando a animação de abertura é concluída.
close	Disparado quando o componente começa a fechar.
closed	Disparado quando a animação de fechamento é concluída.

### Slots

Nome	Descrição
(padrão)	Conteúdo do corpo do item de painel expansível.
header	Conteúdo do cabeçalho do item de painel expansível.

### CSS Parts

Nome	Descrição
header	Conteúdo do cabeçalho do painel expansível.
body	Conteúdo do corpo do painel expansível.

## mdui-collapse API ### Propriedades

Atributo Propriedade Reflect Tipo Padrão Descrição

accordion

true

boolean

false

Define se o modo acordeão deve ser ativado.

value

false

string | string[]

O valor do <mdui-collapse-item> atualmente expandido.

Nota: O atributo HTML desta propriedade é sempre uma string e só pode definir o valor inicial quando accordion é true; o valor da propriedade JavaScript é uma string quando accordion é true, e um array de strings quando accordion é false. Portanto, quando accordion é false, só é possível alterar este valor modificando a propriedade JavaScript.

disabled

true

boolean

false

Define se este painel expansível está desabilitado.

### Eventos

Nome	Descrição
change	Disparado quando o item do painel expansível atualmente expandido muda.

### Slots

Nome	Descrição
(padrão)	Componentes `<mdui-collapse-item>`.

# Componente Dialog O diálogo fornece alertas importantes durante o fluxo de ações do usuário. Além de usar o componente diretamente, mdui também fornece quatro funções: [`mdui.dialog`](/pt-br/docs/2/functions/dialog), [`mdui.alert`](/pt-br/docs/2/functions/alert), [`mdui.confirm`](/pt-br/docs/2/functions/confirm), [`mdui.prompt`](/pt-br/docs/2/functions/prompt). Essas funções simplificam o uso do componente Dialog. ## Como usar {#usage} Importe o componente quando necessário: ```js import 'mdui/components/dialog.js'; ``` Importe o tipo TypeScript do componente quando necessário: ```ts import type { Dialog } from 'mdui/components/dialog.js'; ``` Exemplo de uso: ```html Dialog Fechar

Abrir diálogo

``` ## Exemplos {#examples} ### Fechar ao clicar na sobreposição {#example-close-on-overlay-click} Use o atributo `close-on-overlay-click` para fechar o diálogo ao clicar na sobreposição. ```html Dialog

Abrir diálogo

``` ### Fechar ao pressionar a tecla ESC {#example-close-on-esc} Use o atributo `close-on-esc` para fechar o diálogo ao pressionar a tecla ESC. ```html Dialog

Abrir diálogo

``` ### Tela cheia {#example-fullscreen} Use o atributo `fullscreen` para exibir o diálogo em tela cheia. ```html Dialog Fechar

Abrir diálogo

``` ### Ícone {#example-icon} Defina o atributo `icon` para adicionar um ícone do Material Icons na parte superior do diálogo. ```html Dialog

Abrir diálogo

``` Você também pode adicionar um elemento de ícone na parte superior do diálogo pelo slot `icon`. ```html Dialog

Abrir diálogo

``` ### Título e descrição {#example-headline} Defina o título e a descrição do diálogo pelos atributos `headline` e `description`. ```html

Abrir diálogo

``` Você também pode definir o elemento do título e descrição pelos slots `headline` e `description`. ```html Delete selected images? Images will be permanently removed from your account and all synced devices.

Abrir diálogo

``` ### Botões de ação inferiores {#example-action} Você pode adicionar botões de ação inferiores pelo slot `action`. ```html

Cancelar

Deletar

Abrir diálogo

``` Use o atributo `stacked-actions` para organizar os botões de ação inferiores verticalmente. ```html

Turn on speed boost

No thanks

Abrir diálogo

``` ### Conteúdo superior {#example-header} Você pode definir o conteúdo superior do diálogo pelo slot `header`. ```html

Title

Save

Abrir diálogo

``` ## mdui-dialog API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
icon	icon	true	string		Nome do ícone Material Icons no topo. Também pode ser definido via `slot="icon"`.
headline	headline	true	string		Título. Também pode ser definido via `slot="headline"`.
description	description	true	string		Texto abaixo do título. Também pode ser definido via `slot="description"`.
open	open	true	boolean	false	Define se o diálogo está aberto.
fullscreen	fullscreen	true	boolean	false	Define se o diálogo deve ser exibido em tela cheia.
close-on-esc	closeOnEsc	true	boolean	false	Define se é permitido fechar o diálogo pressionando a tecla ESC.
close-on-overlay-click	closeOnOverlayClick	true	boolean	false	Define se é permitido fechar o diálogo clicando na camada de sobreposição.
stacked-actions	stackedActions	true	boolean	false	Define se os botões de ação na parte inferior devem ser empilhados verticalmente.

### Eventos

Nome	Descrição
open	Disparado quando o diálogo começa a abrir. Pode impedir a abertura chamando `event.preventDefault()`.
opened	Disparado quando a animação de abertura do diálogo é concluída.
close	Disparado quando o diálogo começa a fechar. Pode impedir o fechamento chamando `event.preventDefault()`.
closed	Disparado quando a animação de fechamento do diálogo é concluída.
overlay-click	Disparado ao clicar na camada de sobreposição.

### Slots

Nome	Descrição
header	Elemento do topo. Contém, por padrão, o slot `icon` e o slot `headline`.
icon	Ícone do topo.
headline	Título do topo.
description	Texto abaixo do título.
(padrão)	Conteúdo principal do diálogo.
action	Elementos na barra de ação inferior.

### CSS Parts

Nome	Descrição
overlay	Camada de sobreposição.
panel	Contêiner do diálogo.
header	Parte do cabeçalho do diálogo. Contém ícone e título.
icon	Ícone do topo, localizado no cabeçalho.
headline	Título do topo, localizado no cabeçalho.
body	Parte do corpo do diálogo.
description	Parte do texto secundário, localizada no corpo.
action	Botões de ação na parte inferior.

### Propriedades CSS personalizadas

Nome	Descrição
--shape-corner	Tamanho da borda arredondada do componente. Pode ser um valor em pixels, mas é recomendado usar os design tokens.
--z-index	Valor CSS `z-index` do componente.

# Componente Divider O divisor é uma linha fina que agrupa conteúdo em listas e contêineres. ## Como usar {#usage} Importe o componente quando necessário: ```js import 'mdui/components/divider.js'; ``` Importe o tipo TypeScript do componente quando necessário: ```ts import type { Divider } from 'mdui/components/divider.js'; ``` Exemplo de uso: ```html ``` ## Exemplos {#examples} ### Divisor vertical {#example-vertical} Use o atributo `vertical` para exibir o divisor verticalmente. ```html

``` ### Recuo à esquerda {#example-inset} Use o atributo `inset` para recuar o divisor à esquerda. Isso é frequentemente usado em listas para alinhar o divisor com o texto. ```html

Item 1

Item 2

``` ### Recuo em ambos os lados {#example-middle} Use o atributo `middle` para recuar o divisor em ambos os lados. ```html

Item 1

Item 2

``` ## mdui-divider API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
vertical	vertical	true	boolean	false	Define se é um divisor vertical.
inset	inset	true	boolean	false	Define se deve ter recuo à esquerda.
middle	middle	true	boolean	false	Define se deve ter recuo em ambos os lados.

# Componente Dropdown O Dropdown exibe conteúdo específico em um controle suspenso, geralmente usado com o componente de menu. ## Como usar {#usage} Importe o componente quando necessário: ```js import 'mdui/components/dropdown.js'; ``` Importe o tipo TypeScript do componente quando necessário: ```ts import type { Dropdown } from 'mdui/components/dropdown.js'; ``` Exemplo de uso: ```html

open dropdown

Item 1

Item 2

``` ## Exemplos {#examples} ### Estado desabilitado {#example-disabled} Use o atributo `disabled` para desabilitar o dropdown. ```html

open dropdown

Item 1

Item 2

``` ### Posição de abertura {#example-placement} Use o atributo `placement` para definir a posição de abertura do dropdown. ```html

open dropdown

Item 1

Item 2

``` ### Modo de acionamento {#example-trigger} Use o atributo `trigger` para definir o modo de acionamento do dropdown. ```html

open dropdown

Item 1

Item 2

``` ### Abrir na posição do cursor {#example-open-on-pointer} Use o atributo `open-on-pointer` para abrir o dropdown na posição do cursor. Geralmente usado com `trigger="contextmenu"` para abrir o menu com o botão direito do mouse. ```html

Clique com o botão direito nesta área para abrir o menu

Item 1

Item 2

``` ### Manter o menu aberto ao clicar {#example-stay-open-on-click} Ao usar o menu no dropdown, por padrão, clicar em um item do menu fecha o dropdown. Use o atributo `stay-open-on-click` para manter o dropdown aberto ao clicar em um item do menu. ```html

open dropdown

Item 1

Item 2

``` ### Atraso para abrir/fechar {#example-delay} Quando `trigger="hover"`, você pode usar os atributos `open-delay` e `close-delay` para definir o atraso para abrir e fechar. ```html

open dropdown

Item 1

Item 2

``` ## mdui-dropdown API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
open	open	true	boolean	false	Define se o dropdown está aberto.
disabled	disabled	true	boolean	false	Define se o dropdown está desabilitado.
trigger	trigger	true	'click' \| 'hover' \| 'focus' \| 'contextmenu' \| 'manual' \| string	'click'	Forma de acionamento do dropdown. Suporta múltiplos valores separados por espaço. Os valores possíveis são: `click`: Aciona ao clicar. `hover`: Aciona ao passar o mouse. `focus`: Aciona ao receber foco. `contextmenu`: Aciona ao clicar com o botão direito do mouse ou toque longo. `manual`: Só pode ser aberto e fechado programaticamente. Não pode ser combinado com outras formas de acionamento.
placement	placement	true	'auto' \| 'top-start' \| 'top' \| 'top-end' \| 'bottom-start' \| 'bottom' \| 'bottom-end' \| 'left-start' \| 'left' \| 'left-end' \| 'right-start' \| 'right' \| 'right-end'	'auto'	Posição do conteúdo do dropdown. Os valores possíveis são: `auto`: Posição automática. `top-start`: Acima, alinhado à esquerda. `top`: Acima, centralizado. `top-end`: Acima, alinhado à direita. `bottom-start`: Abaixo, alinhado à esquerda. `bottom`: Abaixo, centralizado. `bottom-end`: Abaixo, alinhado à direita. `left-start`: À esquerda, alinhado ao topo. `left`: À esquerda, centralizado. `left-end`: À esquerda, alinhado à base. `right-start`: À direita, alinhado ao topo. `right`: À direita, centralizado. `right-end`: À direita, alinhado à base.
stay-open-on-click	stayOpenOnClick	true	boolean	false	Define se, após clicar em um `<mdui-menu-item>`, o dropdown deve permanecer aberto.
open-delay	openDelay	true	number	150	Atraso, em milissegundos, para abrir o dropdown ao passar o mouse.
close-delay	closeDelay	true	number	150	Atraso, em milissegundos, para fechar o dropdown ao passar o mouse.
open-on-pointer	openOnPointer	true	boolean	false	Define se o dropdown deve abrir na posição do cursor que o acionou. Usado frequentemente para abrir menus de contexto do mouse.

### Eventos

Nome	Descrição
open	Disparado quando o dropdown começa a abrir. Pode impedir a abertura chamando `event.preventDefault()`.
opened	Disparado quando a animação de abertura do dropdown é concluída.
close	Disparado quando o dropdown começa a fechar. Pode impedir o fechamento chamando `event.preventDefault()`.
closed	Disparado quando a animação de fechamento do dropdown é concluída.

### Slots

Nome	Descrição
(padrão)	Conteúdo do dropdown.
trigger	Elemento que aciona o dropdown, por exemplo, um elemento `<mdui-button>`.

### CSS Parts

Nome	Descrição
trigger	Contêiner do elemento que aciona o dropdown, ou seja, o contêiner do slot `trigger`.
panel	Contêiner do conteúdo do dropdown.

### Propriedades CSS personalizadas

Nome	Descrição
--z-index	Valor CSS `z-index` do componente.

# Componente Fab O botão de ação flutuante (FAB) destaca a ação principal na página, colocando-a em um local de fácil acesso. ## Como usar {#usage} Importe o componente quando necessário: ```js import 'mdui/components/fab.js'; ``` Importe o tipo TypeScript do componente quando necessário: ```ts import type { Fab } from 'mdui/components/fab.js'; ``` Exemplo de uso: ```html ``` ## Exemplos {#examples} ### Ícone {#example-icon} Use o atributo `icon` para definir o nome do ícone do Material Icons. Você também pode adicionar o elemento do ícone pelo slot `icon`. ```html

``` ### Estado estendido {#example-extended} Use o atributo `extended` para colocar o FAB no estado estendido. Assim, o texto no slot padrão será exibido. ```html Compose ``` ### Forma {#example-variant} Use o atributo `variant` para definir a forma do FAB. ```html

``` ### Tamanho {#example-size} Use o atributo `size` para definir o tamanho do FAB. ```html

``` ### Link {#example-link} Use o atributo `href` para transformar o FAB em um link. Assim, você também pode usar os atributos relacionados a links: `download`, `target`, `rel`. ```html ``` ### Estado desabilitado e carregando {#example-disabled} Use o atributo `disabled` para desabilitar o FAB; adicione o atributo `loading` para adicionar um estado de carregamento ao FAB. ```html

``` ## mdui-fab API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
variant	variant	true	'primary' \| 'surface' \| 'secondary' \| 'tertiary'	'primary'	Forma do FAB. As variantes deste componente diferem apenas na cor. Os valores possíveis são: `primary`: Usa a cor de fundo do contêiner primário. `surface`: Usa a cor de fundo alta do contêiner de superfície. `secondary`: Usa a cor de fundo do contêiner secundário. `tertiary`: Usa a cor de fundo do contêiner terciário.
size	size	true	'normal' \| 'small' \| 'large'	'normal'	Tamanho do FAB. Os valores possíveis são: `normal`: Tamanho normal. `small`: Tamanho pequeno. `large`: Tamanho grande.
icon	icon	true	string		Nome do ícone Material Icons. Também pode ser definido via `slot="icon"`.
extended	extended	true	boolean	false	Define se o componente está no estado expandido.
href	href	true	string		A URL de destino do link. Ao definir esta propriedade, o componente será renderizado internamente como um elemento `<a>` e poderá usar atributos de link.
download	download	true	string		O nome do arquivo para download. Nota: Esta propriedade só é válida quando o atributo `href` está definido.
target	target	true	'_blank' \| '_parent' \| '_self' \| '_top'		Define como o link será aberto. Os valores possíveis são: `_blank`: Abre o link em uma nova janela `_parent`: Abre o link no frame pai `_self`: Padrão. Abre o link no frame atual `_top`: Abre o link na janela inteira Nota: Esta propriedade só é válida quando o atributo `href` está definido.
rel	rel	true	'alternate' \| 'author' \| 'bookmark' \| 'external' \| 'help' \| 'license' \| 'me' \| 'next' \| 'nofollow' \| 'noreferrer' \| 'opener' \| 'prev' \| 'search' \| 'tag'		A relação entre o documento atual e o documento vinculado. Os valores possíveis são: `alternate`: Versão alternativa do documento atual `author`: Autor do documento atual ou artigo `bookmark`: Link permanente para a seção ancestral mais próxima `external`: O documento referenciado não está no mesmo site do documento atual `help`: Link para documentação de ajuda relacionada `license`: O conteúdo principal do documento atual está coberto pela licença de direitos autorais do arquivo referenciado `me`: O documento atual representa o proprietário do conteúdo vinculado `next`: O documento atual faz parte de uma série, e o documento referenciado é o próximo da série `nofollow`: O autor ou editor do documento atual não endossa o arquivo referenciado `noreferrer`: Não inclui o cabeçalho `Referer`. Tem efeito semelhante ao `noopener` `opener`: Se o hiperlink criar um contexto de navegação de nível superior (ou seja, o valor do atributo `target` for `_blank`), cria um contexto de navegação auxiliar `prev`: O documento atual faz parte de uma série, e o documento referenciado é o anterior da série `search`: Fornece um link para um recurso que pode ser usado para pesquisar o arquivo atual e suas páginas relacionadas `tag`: Fornece uma tag (identificada pelo endereço fornecido) aplicável ao documento atual Nota: Disponível apenas quando o atributo `href` é especificado.
autofocus	autofocus	true	boolean	false	Define se o elemento deve receber foco automaticamente após o carregamento da página.
tabindex	tabIndex	false	number		A ordem do elemento ao navegar com a tecla Tab.
disabled	disabled	true	boolean	false	Define se o componente está desabilitado.
loading	loading	true	boolean	false	Define se o componente está em estado de carregamento.
name	name	true	string	''	O nome do botão, que será enviado com os dados do formulário. Nota: Esta propriedade só é válida quando o atributo `href` não está definido.
value	value	true	string	''	O valor inicial do botão, que será enviado com os dados do formulário. Nota: Esta propriedade só é válida quando o atributo `href` não está definido.
type	type	true	'submit' \| 'reset' \| 'button'	'button'	O tipo do botão. O tipo padrão é `button`. Os tipos possíveis são: `submit`: Clicar no botão envia os dados do formulário para o servidor `reset`: Clicar no botão redefine todos os campos do formulário para seus valores iniciais `button`: Este tipo de botão não tem comportamento padrão Nota: Esta propriedade só é válida quando o atributo `href` não é especificado.
form	form	true	string		O elemento `<form>` associado. O valor deste atributo deve ser o `id` de um elemento `<form>` na mesma página. Se este atributo não for especificado, o elemento precisa ser um elemento filho de um `<form>`. Com este atributo, você pode colocar o elemento em qualquer lugar da página, não apenas como filho do elemento `<form>`. Nota: Esta propriedade só é válida quando o atributo `href` não é especificado.
formaction	formAction	true	string		Especifica a URL para envio do formulário. Se este atributo for especificado, ele substituirá o atributo `action` do elemento `<form>`. Nota: Esta propriedade só é válida quando o atributo `href` não é especificado e `type="submit"`.
formenctype	formEnctype	true	'application/x-www-form-urlencoded' \| 'multipart/form-data' \| 'text/plain'		Especifica o tipo de conteúdo ao enviar o formulário para o servidor. Os valores possíveis são: `application/x-www-form-urlencoded`: Valor padrão quando o atributo não é especificado `multipart/form-data`: Usado quando o formulário contém um elemento `<input type="file">` `text/plain`: Novo no HTML5, usado para depuração Se este atributo for especificado, ele substituirá o atributo `enctype` do elemento `<form>`. Nota: Esta propriedade só é válida quando o atributo `href` não é especificado e `type="submit"`.
formmethod	formMethod	true	'post' \| 'get'		Especifica o método HTTP a ser usado ao enviar o formulário. Os valores possíveis são: `post`: Os dados do formulário são incluídos no corpo do formulário e enviados ao servidor `get`: Os dados do formulário são anexados à URI do formulário com `?` 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 Se este atributo for definido, ele substituirá o atributo `method` do elemento `<form>`. Nota: Esta propriedade só é válida quando o atributo `href` não é definido e `type="submit"`.
formnovalidate	formNoValidate	true	boolean	false	Se este atributo for definido, a validação do formulário não será executada ao enviar. Se este atributo for definido, ele substituirá o atributo `novalidate` do elemento `<form>`. Nota: Esta propriedade só é válida quando o atributo `href` não é definido e `type="submit"`.
formtarget	formTarget	true	'_self' \| '_blank' \| '_parent' \| '_top'		Onde exibir a resposta recebida após o envio do formulário. Os valores possíveis são: `_self`: Opção padrão, abre no frame atual `_blank`: Abre em uma nova janela `_parent`: Abre no frame pai `_top`: Abre na janela inteira Se este atributo for definido, ele substituirá o atributo `target` do elemento `<form>`. Nota: Esta propriedade só é válida quando o atributo `href` não é definido e `type="submit"`.
undefined	validity	false	ValidityState		Objeto que representa o estado de validação do formulário. Consulte `ValidityState` para mais detalhes.
undefined	validationMessage	false	string		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.

### Métodos

Nome	Descrição
click(): void	Simula um clique do mouse no elemento.
focus(options?: FocusOptions): void	Define o foco no elemento atual. Você pode passar um objeto como argumento, com as seguintes propriedades: `preventScroll`: 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 `true`.
blur(): void	Remove o foco do elemento atual.
checkValidity(): boolean	Verifica se o campo do formulário passou na validação. Se não passou, retorna `false` e dispara o evento `invalid`; se passou, retorna `true`.
reportValidity(): boolean	Verifica se o campo do formulário passou na validação. Se não passou, retorna `false` e dispara o evento `invalid`; se passou, retorna `true`. Se a validação falhar, também exibe uma mensagem de erro no componente.
setCustomValidity(message: string): void	Define um texto de erro personalizado. Enquanto este texto não estiver vazio, indica que o campo não passou na validação.

### Eventos

Nome	Descrição
focus	Disparado ao receber foco.
blur	Disparado ao perder o foco.
invalid	Disparado quando a validação do campo do formulário falha.

### Slots

Nome	Descrição
(padrão)	Texto.
icon	Ícone.

### CSS Parts

Nome	Descrição
button	Elemento `<button>` ou `<a>` interno.
label	Texto à direita.
icon	Ícone à esquerda.
loading	Elemento `<mdui-circular-progress>` no estado de carregamento.

### Propriedades CSS personalizadas

Nome	Descrição
--shape-corner-small	Tamanho da borda arredondada do componente quando `size="small"`. Pode ser um valor em pixels, mas é recomendado usar os design tokens.
--shape-corner-normal	Tamanho da borda arredondada do componente quando `size="normal"`. Pode ser um valor em pixels, mas é recomendado usar os design tokens.
--shape-corner-large	Tamanho da borda arredondada do componente quando `size="large"`. Pode ser um valor em pixels, mas é recomendado usar os design tokens.

# Componente Icon O ícone representa ações comuns. Ele suporta ícones do Material Icons e também ícones SVG. ## Como usar {#usage} Importe o componente quando necessário: ```js import 'mdui/components/icon.js'; ``` Importe o tipo TypeScript do componente quando necessário: ```ts import type { Icon } from 'mdui/components/icon.js'; ``` Exemplo de uso: ```html ``` ### Usar ícones do Material Icons {#usage-material-icons} Para usar ícones do Material Icons por este componente, você precisa importar o arquivo CSS do Material Icons separadamente. O Material Icons possui 5 variantes: Filled, Outlined, Rounded, Sharp, Two Tone. Importe o arquivo CSS correspondente à variante desejada: ```html ``` Ao usar o componente, passe o nome do ícone no atributo `name` e adicione o sufixo do nome da variante (a variante Filled não precisa de sufixo). Exemplo de uso das 5 variantes do ícone `delete`: ```html

``` Você pode pesquisar ícones na ferramenta [Pesquisa de ícones do Material Icons](/pt-br/docs/2/components/icon#search) na parte inferior da página. Clique no ícone que deseja usar para copiar o código do ícone para a área de transferência. Além disso, O mdui oferece um pacote independente [`@mdui/icons`](/pt-br/docs/2/libraries/icons), onde cada componente de ícone é um arquivo independente, permitindo que você importe apenas os componentes de ícone necessários, sem precisar importar toda a biblioteca de ícones. ### Usar ícones SVG {#usage-svg} Este componente também suporta ícones SVG como conteúdo. Você pode passar o link do ícone SVG pelo atributo `src`. Exemplos: ```html ``` Você também pode passar o conteúdo SVG no slot padrão do componente. Exemplos: ```html ``` ## Exemplos {#examples} ### Definir cor {#example-color} Modifique a cor do ícone pelo estilo CSS `color` no elemento `` ou em seu elemento pai. ```html ``` ### Definir tamanho {#example-size} Modifique o tamanho do ícone pelo estilo CSS `font-size` no elemento `` ou em seu elemento pai. ```html ``` ## mdui-icon API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
name	name	true	string		Nome do ícone Material Icons.
src	src	true	string		Caminho do ícone SVG.

### Slots

Nome	Descrição
(padrão)	Conteúdo do ícone `svg`.

# Componente Layout O componente layout oferece um sistema de layout flexível para criar layouts de página complexos. ## Como usar {#usage} Importe os componentes quando necessário: ```js import 'mdui/components/layout.js'; import 'mdui/components/layout-item.js'; import 'mdui/components/layout-main.js'; ``` Importe os tipos TypeScript dos componentes quando necessário: ```ts import type { Layout } from 'mdui/components/layout.js'; import type { LayoutItem } from 'mdui/components/layout-item.js'; import type { LayoutMain } from 'mdui/components/layout-main.js'; ``` **Introdução:** O sistema de layout segue o princípio de construção de fora para dentro. Cada componente de layout (componente ``) ocupa espaço em uma das quatro direções (cima, baixo, esquerda, direita). Os componentes de layout subsequentes ocupam espaço no espaço restante. Os seguintes componentes herdam diretamente do componente `` e, portanto, também podem ser usados como componentes de layout: - [``](/pt-br/docs/2/components/navigation-bar) - [``](/pt-br/docs/2/components/navigation-drawer) - [``](/pt-br/docs/2/components/navigation-rail) - [``](/pt-br/docs/2/components/bottom-app-bar) - [``](/pt-br/docs/2/components/top-app-bar) A parte final do sistema de layout é o componente ``, que ocupa o espaço restante. Você pode colocar o conteúdo da página dentro deste componente. ## Exemplos {#examples} ### Ordem dos componentes de layout {#layout-default-order} Por padrão, os componentes de layout ocupam espaço na ordem em que aparecem no código. Você pode entender esse conceito pelos dois exemplos abaixo, onde a ordem de [``](/pt-br/docs/2/components/top-app-bar) e [``](/pt-br/docs/2/components/navigation-drawer) no código é diferente.

Veja este exemplo em um monitor maior.

```html

Top App Bar

Main

``` ```html

Top App Bar

Main

``` Observe que, quando [``](/pt-br/docs/2/components/top-app-bar) é colocado antes de [``](/pt-br/docs/2/components/navigation-drawer), [``](/pt-br/docs/2/components/top-app-bar) ocupará primeiro toda a largura da tela, enquanto [``](/pt-br/docs/2/components/navigation-drawer) só poderá ocupar a altura no espaço restante. Invertendo a ordem, [``](/pt-br/docs/2/components/navigation-drawer) ocupará primeiro toda a altura da tela, e [``](/pt-br/docs/2/components/top-app-bar) só poderá ocupar a largura no espaço restante. ### Posição dos componentes de layout {#example-placement} Para o componente ``, você pode usar o atributo `placement` para definir sua posição no layout (cima, baixo, esquerda, direita). Para os componentes [``](/pt-br/docs/2/components/navigation-drawer) e [``](/pt-br/docs/2/components/navigation-rail), você também pode usar o atributo `placement` para definir sua posição à esquerda ou direita. No exemplo abaixo, colocamos dois componentes `` em ambos os lados do aplicativo. ```html

Top App Bar

Layout Item

Main

``` ### Ordem personalizada dos componentes de layout {#example-order} Na maioria dos casos, colocar os componentes de layout em ordem é suficiente para obter o layout desejado. Você também pode usar o atributo `order` para definir a ordem de layout. O sistema organizará os componentes em ordem crescente de `order`. Se `order` for igual, a ordem do código será usada. O valor padrão de `order` para todos os componentes de layout é `0`. ```html

Layout Item

Top App Bar

order="-1"

Main

``` ## mdui-layout-item API ### Propriedades

Atributo Propriedade Reflect Tipo Padrão Descrição

placement

true

'top' | 'bottom' | 'left' | 'right'

'top'

Posição do componente. Os valores possíveis são:

top: Superior.
bottom: Inferior.
left: Esquerda.
right: Direita.

order

true

number

A ordem de layout deste componente dentro do <mdui-layout>, em ordem crescente. O valor padrão é 0.

### Slots

Nome	Descrição
(padrão)	Pode conter qualquer conteúdo.

## mdui-layout-main API ### Slots

Nome	Descrição
(padrão)	Pode conter qualquer conteúdo.

## mdui-layout API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
full-height	fullHeight	true	boolean	false	Define a altura do layout como 100%.

### Slots

Nome	Descrição
(padrão)	Pode conter elementos `<mdui-top-app-bar>`, `<mdui-bottom-app-bar>`, `<mdui-navigation-bar>`, `<mdui-navigation-drawer>`, `<mdui-navigation-rail>`, `<mdui-layout-item>`, `<mdui-layout-main>`.

# Componente LinearProgress O indicador de progresso linear mostra o andamento de uma tarefa ao usuário, como carregamento de dados ou envio de formulário. ## Como usar {#usage} Importe o componente quando necessário: ```js import 'mdui/components/linear-progress.js'; ``` Importe o tipo TypeScript do componente quando necessário: ```ts import type { LinearProgress } from 'mdui/components/linear-progress.js'; ``` Exemplo de uso: ```html ``` ## Exemplos {#examples} ### Progresso determinado {#example-value} O indicador de progresso linear por padrão é indeterminado. Você pode definir o progresso atual pelo atributo `value`, onde o valor máximo padrão é `1`. ```html ``` Você também pode definir o valor máximo do progresso pelo atributo `max`. ```html ``` ## mdui-linear-progress API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
max	max	true	number	1	O valor máximo do indicador de progresso. O padrão é `1`.
value	value	false	number		O valor atual do indicador de progresso. Se não for especificado, exibe o estado indeterminado.

### CSS Parts

Nome	Descrição
indicator	Parte do indicador.

### Propriedades CSS personalizadas

Nome	Descrição
--shape-corner	Tamanho da borda arredondada do componente. Pode ser um valor em pixels, mas é recomendado usar os design tokens.

# Componente List Lista é um índice vertical usado para exibir texto ou imagens, facilitando a navegação rápida e o acesso a informações relacionadas. ## Como usar {#usage} Importe os componentes conforme necessário: ```js import 'mdui/components/list.js'; import 'mdui/components/list-item.js'; import 'mdui/components/list-subheader.js'; ``` Importe os tipos TypeScript dos componentes conforme necessário: ```ts import type { List } from 'mdui/components/list.js'; import type { ListItem } from 'mdui/components/list-item.js'; import type { ListSubheader } from 'mdui/components/list-subheader.js'; ``` Exemplo de uso: ```html

Subheader

Item 1

Item 2

``` ## Exemplos {#examples} ### Conteúdo de texto {#example-text} Defina o atributo `headline` no componente `` para definir o texto principal do item da lista, e o atributo `description` para definir o texto secundário. ```html

``` Você também pode definir o texto principal pelo slot padrão e o texto secundário pelo slot `description`. ```html

Headline

Headline Supporting text

``` Por padrão, o texto principal e o secundário são exibidos integralmente, independentemente do comprimento. Você pode definir os atributos `headline-line` e `description-line` para limitar o número de linhas do texto principal e secundário, no máximo 3 linhas. ```html

Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text

``` ### Conteúdo nas laterais {#example-side} Defina os atributos `icon` e `end-icon` no componente `` para adicionar ícones do Material Icons à esquerda e à direita do item da lista. ```html

Headline

``` Você também pode adicionar elementos à esquerda e à direita pelos slots `icon` e `end-icon`. ```html

Headline

``` ### Link {#example-link} Defina o atributo `href` para transformar o item da lista em um link. Assim, você também pode usar os atributos relacionados a links: `download`, `target` e `rel`. ```html

Headline

``` ### Estado desabilitado {#example-disabled} Use o atributo `disabled` no componente `` para desabilitar o item da lista. Assim, componentes como checkbox, radio, switch dentro do item da lista também serão desabilitados. ```html

Headline

``` ### Estado ativo {#example-active} Use o atributo `active` no componente `` para ativar o item da lista. ```html

Headline

``` ### Estado não clicável {#example-nonclickable} Use o atributo `nonclickable` no componente `` para remover o efeito de hover e ondulação do item da lista. ```html

Headline

``` ### Forma arredondada {#example-rounded} Use o atributo `rounded` no componente `` para dar uma forma arredondada ao item da lista. ```html

Headline

``` ### Alinhamento vertical {#example-alignment} Defina o atributo `alignment` no componente `` para ajustar o alinhamento dos elementos laterais em relação ao item da lista. Os valores possíveis são: - `start`: alinhado ao topo - `center`: alinhado ao centro - `end`: alinhado à base ```html

Headline

``` ### Conteúdo personalizado {#example-custom} Use o slot `custom` no componente `` para personalizar completamente o conteúdo do item da lista. ```html

test

``` ## mdui-list-item API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
headline	headline	true	string		Texto principal. Também pode ser definido via slot padrão.
headline-line	headlineLine	true	1 \| 2 \| 3		Número de linhas do texto principal. Será truncado se exceder o limite. O padrão é sem limite de linhas. Os valores possíveis são: `1`: Exibe uma linha; trunca se exceder. `2`: Exibe duas linhas; trunca se exceder. `3`: Exibe três linhas; trunca se exceder.
description	description	true	string		Texto secundário. Também pode ser definido via `slot="description"`.
description-line	descriptionLine	true	1 \| 2 \| 3		Número de linhas do texto secundário. Será truncado se exceder o limite. O padrão é sem limite de linhas. Os valores possíveis são: `1`: Exibe uma linha; trunca se exceder. `2`: Exibe duas linhas; trunca se exceder. `3`: Exibe três linhas; trunca se exceder.
icon	icon	true	string		Nome do ícone Material Icons à esquerda. Também pode ser definido via `slot="icon"`.
end-icon	endIcon	true	string		Nome do ícone Material Icons à direita. Também pode ser definido via `slot="end-icon"`.
disabled	disabled	true	boolean	false	Define se este item da lista está desabilitado. Quando desabilitado, o item da lista fica cinza, e elementos como `<mdui-checkbox>`, `<mdui-radio>` e `<mdui-switch>` dentro dele também são desabilitados.
active	active	true	boolean	false	Define se este item da lista está ativo.
nonclickable	nonclickable	true	boolean	false	Torna o item da lista não clicável. Quando definido, ainda é possível interagir com elementos como `<mdui-checkbox>`, `<mdui-radio>` e `<mdui-switch>` dentro dele.
rounded	rounded	true	boolean	false	Define se deve ser usado um item da lista com formato arredondado.
alignment	alignment	true	'start' \| 'center' \| 'end'	'center'	Alinhamento vertical do item da lista. Os valores possíveis são: `start`: Alinhado ao topo. `center`: Alinhado ao centro. `end`: Alinhado à base.
href	href	true	string		A URL de destino do link. Ao definir esta propriedade, o componente será renderizado internamente como um elemento `<a>` e poderá usar atributos de link.
download	download	true	string		O nome do arquivo para download. Nota: Esta propriedade só é válida quando o atributo `href` está definido.
target	target	true	'_blank' \| '_parent' \| '_self' \| '_top'		Define como o link será aberto. Os valores possíveis são: `_blank`: Abre o link em uma nova janela `_parent`: Abre o link no frame pai `_self`: Padrão. Abre o link no frame atual `_top`: Abre o link na janela inteira Nota: Esta propriedade só é válida quando o atributo `href` está definido.
rel	rel	true	'alternate' \| 'author' \| 'bookmark' \| 'external' \| 'help' \| 'license' \| 'me' \| 'next' \| 'nofollow' \| 'noreferrer' \| 'opener' \| 'prev' \| 'search' \| 'tag'		A relação entre o documento atual e o documento vinculado. Os valores possíveis são: `alternate`: Versão alternativa do documento atual `author`: Autor do documento atual ou artigo `bookmark`: Link permanente para a seção ancestral mais próxima `external`: O documento referenciado não está no mesmo site do documento atual `help`: Link para documentação de ajuda relacionada `license`: O conteúdo principal do documento atual está coberto pela licença de direitos autorais do arquivo referenciado `me`: O documento atual representa o proprietário do conteúdo vinculado `next`: O documento atual faz parte de uma série, e o documento referenciado é o próximo da série `nofollow`: O autor ou editor do documento atual não endossa o arquivo referenciado `noreferrer`: Não inclui o cabeçalho `Referer`. Tem efeito semelhante ao `noopener` `opener`: Se o hiperlink criar um contexto de navegação de nível superior (ou seja, o valor do atributo `target` for `_blank`), cria um contexto de navegação auxiliar `prev`: O documento atual faz parte de uma série, e o documento referenciado é o anterior da série `search`: Fornece um link para um recurso que pode ser usado para pesquisar o arquivo atual e suas páginas relacionadas `tag`: Fornece uma tag (identificada pelo endereço fornecido) aplicável ao documento atual Nota: Disponível apenas quando o atributo `href` é especificado.
autofocus	autofocus	true	boolean	false	Define se o elemento deve receber foco automaticamente após o carregamento da página.
tabindex	tabIndex	false	number		A ordem do elemento ao navegar com a tecla Tab.

### Métodos

Nome Descrição

click(): void

Simula um clique do mouse no elemento.

focus(options?: FocusOptions): void

Define o foco no elemento atual.

Você pode passar um objeto como argumento, com as seguintes propriedades:

preventScroll: 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 true.

blur(): void

Remove o foco do elemento atual.

### Eventos

Nome	Descrição
focus	Disparado ao receber foco.
blur	Disparado ao perder o foco.

### Slots

Nome	Descrição
(padrão)	Texto principal.
description	Texto secundário.
icon	Elemento à esquerda do item da lista.
end-icon	Elemento à direita do item da lista.
custom	Qualquer conteúdo personalizado.

### CSS Parts

Nome	Descrição
container	Contêiner do item da lista.
icon	Ícone à esquerda.
end-icon	Ícone à direita.
body	Parte do meio.
headline	Título principal.
description	Subtítulo.

### Propriedades CSS personalizadas

Nome	Descrição
--shape-corner	Tamanho da borda arredondada do item da lista. Pode ser um valor em pixels, mas é recomendado usar os design tokens.
--shape-corner-rounded	Tamanho da borda arredondada do item da lista quando o atributo `rounded` é especificado. Pode ser um valor em pixels, mas é recomendado usar os design tokens.

## mdui-list-subheader API ### Slots

Nome	Descrição
(padrão)	Texto do cabeçalho da lista.

## mdui-list API ### Slots

Nome	Descrição
(padrão)	Elementos `<mdui-list-item>`.

# Componente Menu O componente menu fornece uma série de opções dispostas verticalmente. O menu é exibido quando o usuário interage com um botão ou outro controle. Se você precisar implementar um menu suspenso, pode usar o componente [``](/pt-br/docs/2/components/dropdown). ## Como usar {#usage} Importe os componentes conforme necessário: ```js import 'mdui/components/menu.js'; import 'mdui/components/menu-item.js'; ``` Importe os tipos TypeScript dos componentes conforme necessário: ```ts import type { Menu } from 'mdui/components/menu.js'; import type { MenuItem } from 'mdui/components/menu-item.js'; ``` Exemplo de uso: ```html

Item 1

Item 2

``` ## Exemplos {#examples} ### Menu suspenso {#example-dropdown} Use junto com o componente [``](/pt-br/docs/2/components/dropdown) para implementar um menu suspenso. ```html

open dropdown

Item 1

Item 2

``` ### Layout compacto {#example-dense} Use o atributo `dense` no componente `` para obter um layout compacto. ```html

Item 1

Item 2

Item 3

``` ### Desabilitar item do menu {#example-disabled} Use o atributo `disabled` no componente `` para desabilitar o item do menu. ```html

Item 1

Item 2

Item 3

``` ### Suporte a seleção única {#example-selects-single} Defina o atributo `selects` como `single` no componente `` para habilitar a seleção única. Assim, o valor `value` do `` será o valor `value` do `` atualmente selecionado. ```html

Item 1

Item 2

``` ### Suporte a seleção múltipla {#example-selects-multiple} Defina o atributo `selects` como `multiple` no componente `` para habilitar a seleção múltipla. Assim, o valor `value` do `` será um array dos valores `value` dos `` atualmente selecionados. Nota: No modo de seleção múltipla, o valor `value` do `` é um array e só pode ser lido e definido por propriedades JavaScript. ```html

Item 1

Item 2

Item 3

``` ### Ícone {#example-icon} No componente ``, use os atributos `icon` e `end-icon` para adicionar ícones do Material Icons à esquerda e à direita do item do menu, respectivamente. Use o atributo `end-text` para adicionar texto à direita. Além disso, você pode usar os slots `icon`, `end-icon` e `end-text` para adicionar ícones e texto à esquerda e à direita do item do menu. Se você precisar deixar um espaço vazio para ícone à esquerda do item do menu para manter o alinhamento com outros itens, defina o atributo `icon` como uma string vazia. ```html

Item 1

Item 2

Ctrl+X

Item 3

``` No modo de seleção única ou múltipla, você pode usar o atributo `selected-icon` ou o slot `selected-icon` para definir o ícone do estado selecionado. ```html

Item 1

Item 2

``` ### Link {#example-link} Defina o atributo `href` no componente `` para transformar o item do menu em um link. Assim, você também pode usar os atributos relacionados a links: `download`, `target` e `rel`. ```html

Item 1

Item 2

``` ### Submenu {#example-submenu} No componente ``, use o slot `submenu` para especificar os elementos do submenu. ```html

Line spacing Single

1.5

Double

Custom: 1.2

Paragraph style

``` No componente ``, você pode usar o atributo `submenu-trigger` para definir o modo de acionamento do submenu. ```html

Line spacing Single

1.5

Double

Custom: 1.2

Paragraph style

``` Quando `submenu-trigger` é definido como `hover`, você pode usar os atributos `submenu-open-delay` e `submenu-close-delay` no componente `` para definir o atraso de abertura e fechamento do submenu. ```html

Line spacing Single

1.5

Double

Custom: 1.2

Paragraph style

``` ### Conteúdo personalizado {#example-custom} No componente ``, você pode usar o slot `custom` para personalizar completamente o conteúdo do item do menu. ```html

ABS

Retorna o valor absoluto de um número

ACOS

Retorna o arco cosseno de um número, em radianos

ACOSH

Retorna o arco cosseno hiperbólico de um número

``` ## mdui-menu-item API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
value	value	true	string		O valor do item de menu.
disabled	disabled	true	boolean	false	Define se o item de menu está desabilitado.
icon	icon	true	string		Nome do ícone Material Icons à esquerda. Também pode ser definido via `slot="icon"`. Se nenhum ícone precisar ser exibido à esquerda, mas um espaço para ícone for necessário, pode-se passar uma string vazia para reservar o espaço.
end-icon	endIcon	true	string		Nome do ícone Material Icons à direita. Também pode ser definido via `slot="end-icon"`.
end-text	endText	true	string		Texto à direita. Também pode ser definido via `slot="end-text"`.
selected-icon	selectedIcon	true	string		Nome do ícone Material Icons para o estado selecionado. Também pode ser definido via `slot="selected-icon"`.
submenu-open	submenuOpen	true	boolean	false	Define se o submenu está aberto.
href	href	true	string		A URL de destino do link. Ao definir esta propriedade, o componente será renderizado internamente como um elemento `<a>` e poderá usar atributos de link.
download	download	true	string		O nome do arquivo para download. Nota: Esta propriedade só é válida quando o atributo `href` está definido.
target	target	true	'_blank' \| '_parent' \| '_self' \| '_top'		Define como o link será aberto. Os valores possíveis são: `_blank`: Abre o link em uma nova janela `_parent`: Abre o link no frame pai `_self`: Padrão. Abre o link no frame atual `_top`: Abre o link na janela inteira Nota: Esta propriedade só é válida quando o atributo `href` está definido.
rel	rel	true	'alternate' \| 'author' \| 'bookmark' \| 'external' \| 'help' \| 'license' \| 'me' \| 'next' \| 'nofollow' \| 'noreferrer' \| 'opener' \| 'prev' \| 'search' \| 'tag'		A relação entre o documento atual e o documento vinculado. Os valores possíveis são: `alternate`: Versão alternativa do documento atual `author`: Autor do documento atual ou artigo `bookmark`: Link permanente para a seção ancestral mais próxima `external`: O documento referenciado não está no mesmo site do documento atual `help`: Link para documentação de ajuda relacionada `license`: O conteúdo principal do documento atual está coberto pela licença de direitos autorais do arquivo referenciado `me`: O documento atual representa o proprietário do conteúdo vinculado `next`: O documento atual faz parte de uma série, e o documento referenciado é o próximo da série `nofollow`: O autor ou editor do documento atual não endossa o arquivo referenciado `noreferrer`: Não inclui o cabeçalho `Referer`. Tem efeito semelhante ao `noopener` `opener`: Se o hiperlink criar um contexto de navegação de nível superior (ou seja, o valor do atributo `target` for `_blank`), cria um contexto de navegação auxiliar `prev`: O documento atual faz parte de uma série, e o documento referenciado é o anterior da série `search`: Fornece um link para um recurso que pode ser usado para pesquisar o arquivo atual e suas páginas relacionadas `tag`: Fornece uma tag (identificada pelo endereço fornecido) aplicável ao documento atual Nota: Disponível apenas quando o atributo `href` é especificado.
autofocus	autofocus	true	boolean	false	Define se o elemento deve receber foco automaticamente após o carregamento da página.
tabindex	tabIndex	false	number		A ordem do elemento ao navegar com a tecla Tab.

### Métodos

Nome Descrição

click(): void

Simula um clique do mouse no elemento.

focus(options?: FocusOptions): void

Define o foco no elemento atual.

Você pode passar um objeto como argumento, com as seguintes propriedades:

preventScroll: 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 true.

blur(): void

Remove o foco do elemento atual.

### Eventos

Nome	Descrição
focus	Disparado ao receber foco.
blur	Disparado ao perder o foco.
submenu-open	Disparado quando o submenu começa a abrir. Pode impedir a abertura chamando `event.preventDefault()`.
submenu-opened	Disparado quando a animação de abertura do submenu é concluída.
submenu-close	Disparado quando o submenu começa a fechar. Pode impedir o fechamento chamando `event.preventDefault()`.
submenu-closed	Disparado quando a animação de fechamento do submenu é concluída.

### Slots

Nome	Descrição
(padrão)	Texto do item de menu.
icon	Ícone à esquerda do item de menu.
end-icon	Ícone à direita do item de menu.
end-text	Texto à direita do item de menu.
selected-icon	Ícone do estado selecionado.
submenu	Submenu.
custom	Qualquer conteúdo personalizado.

### CSS Parts

Nome	Descrição
container	Contêiner do item de menu.
icon	Ícone à esquerda.
label	Conteúdo de texto.
end-icon	Ícone à direita.
end-text	Texto à direita.
selected-icon	Ícone do estado selecionado.
submenu	Elemento de submenu.

## mdui-menu API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
selects	selects	true	'single' \| 'multiple'		Estado de seleção dos itens do menu. O padrão é não selecionável. Os valores possíveis são: `single`: Seleção única. `multiple`: Seleção múltipla.
value	value	false	string \| string[]		O valor do `<mdui-menu-item>` atualmente selecionado. Nota: O atributo HTML desta propriedade é sempre uma string e só pode definir o valor inicial via atributo HTML quando `selects="single"`; o valor da propriedade JavaScript é uma string quando `selects="single"`, e um array de strings quando `selects="multiple"`. Portanto, quando `selects="multiple"`, para modificar este valor, só é possível alterando a propriedade JavaScript.
dense	dense	true	boolean	false	Define se os itens do menu usam layout compacto.
submenu-trigger	submenuTrigger	true	'click' \| 'hover' \| 'focus' \| 'manual' \| string	'click hover'	Forma de acionamento do submenu. Suporta múltiplos valores separados por espaço. Os valores possíveis são: `click`: Abre o submenu ao clicar no item do menu. `hover`: Abre o submenu ao passar o mouse sobre o item do menu. `focus`: Abre o submenu ao focar no item do menu. `manual`: Só pode ser aberto e fechado programaticamente. Não pode ser combinado com outras formas de acionamento.
submenu-open-delay	submenuOpenDelay	true	number	200	Atraso, em milissegundos, para abrir o submenu ao passar o mouse.
submenu-close-delay	submenuCloseDelay	true	number	200	Atraso, em milissegundos, para fechar o submenu ao passar o mouse.

### Métodos

Nome	Descrição
focus(options?: FocusOptions): void	Define o foco no elemento atual.
blur(): void	Remove o foco do elemento atual.

### Eventos

Nome	Descrição
change	Disparado quando o estado de seleção dos itens do menu muda.

### Slots

Nome	Descrição
(padrão)	Elementos como itens de submenu (`<mdui-menu-item>`), divisores (`<mdui-divider>`), etc.

### Propriedades CSS personalizadas

Nome	Descrição
--shape-corner	Tamanho da borda arredondada do componente. Pode ser um valor em pixels, mas é recomendado usar os design tokens.

# Componente NavigationBar A barra de navegação é usada em páginas móveis para facilitar a alternância entre várias páginas principais. ## Como usar {#usage} Importe os componentes conforme necessário: ```js import 'mdui/components/navigation-bar.js'; import 'mdui/components/navigation-bar-item.js'; ``` Importe os tipos TypeScript dos componentes conforme necessário: ```ts import type { NavigationBar } from 'mdui/components/navigation-bar.js'; import type { NavigationBarItem } from 'mdui/components/navigation-bar-item.js'; ``` Exemplo de uso: (o `style="position: relative"` no exemplo é apenas para fins de demonstração; remova este estilo ao usar.) ```html

Item 1

Item 2

Item 3

``` **Observações:** Este componente usa `position: fixed` por padrão e adiciona automaticamente `padding-bottom` ao `body` para evitar que o conteúdo da página seja ocultado pelo componente. No entanto, nos dois casos a seguir, ele usará `position: absolute` por padrão: 1. Quando o atributo `scroll-target` é especificado. Assim, `padding-bottom` será adicionado ao elemento `scroll-target`. 2. Quando o componente está dentro de [``](/pt-br/docs/2/components/layout). Assim, nenhum `padding-bottom` será adicionado. ## Exemplos {#examples} ### Visibilidade do rótulo de texto {#example-label-visibility} O rótulo de texto na barra de navegação é exibido sempre quando o número de itens de navegação é menor ou igual a 3; quando o número de itens é maior que 3, apenas o texto do item selecionado é exibido. ```html

Item 1

Item 2

Item 3

Item 1

Item 2

Item 3

Item 4

``` Você pode ajustar a visibilidade do rótulo de texto definindo o atributo `label-visibility` no componente ``. Os valores possíveis são: - `selected`: exibe apenas o texto do item selecionado - `labeled`: exibe sempre o texto - `unlabeled`: nunca exibe o texto ```html

Item 1

Item 2

Item 3

selected

labeled

unlabeled

``` ### Dentro de um contêiner especificado {#example-scroll-target} Por padrão, a barra de navegação é exibida na parte inferior da página, em relação à janela atual. Se você deseja colocar a barra de navegação dentro de um contêiner especificado, defina o atributo `scroll-target` no componente ``. O valor deve ser o seletor CSS ou elemento DOM do contêiner de conteúdo rolável. Assim, a barra de navegação será exibida em relação ao elemento pai (você precisa adicionar os estilos `position: relative; overflow: hidden` ao elemento pai). ```html

Item 1

Item 2

Item 3

Conteúdo da página

``` ### Ocultar ao rolar {#example-scroll-behavior} Definindo o atributo `scroll-behavior` como `hide` no componente ``, você pode ocultar a barra de navegação ao rolar a página para baixo e exibi-la ao rolar para cima. Use o atributo `scroll-threshold` para definir quantos pixels rolar antes de começar a ocultar a barra de navegação. ```html

Item 1

Item 2

Item 3

Conteúdo da página

``` ### Ícone {#example-icon} No componente ``, o atributo `icon` é usado para definir o ícone do item de navegação no estado inativo, e o atributo `active-icon` para definir o ícone no estado ativo. Você também pode definir os elementos de ícone para os estados inativo e ativo pelos slots `icon` e `active-icon`. ```html

Item 1

Item 2

``` ### Link {#example-link} Defina o atributo `href` no componente `` para transformar o item de navegação em um link. Assim, você também pode usar os atributos relacionados a links: `download`, `target`, `rel`. ```html

Item 1

Item 2

``` ### Badge {#example-badge} No componente ``, você pode adicionar um badge pelo slot `badge`. ```html

Item 1 99+

Item 2

``` ## mdui-navigation-bar-item API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
icon	icon	true	string		Nome do ícone Material Icons para o estado inativo. Também pode ser definido via `slot="icon"`.
active-icon	activeIcon	true	string		Nome do ícone Material Icons para o estado ativo. Também pode ser definido via `slot="active-icon"`.
value	value	true	string		O valor do item de navegação.
href	href	true	string		A URL de destino do link. Ao definir esta propriedade, o componente será renderizado internamente como um elemento `<a>` e poderá usar atributos de link.
download	download	true	string		O nome do arquivo para download. Nota: Esta propriedade só é válida quando o atributo `href` está definido.
target	target	true	'_blank' \| '_parent' \| '_self' \| '_top'		Define como o link será aberto. Os valores possíveis são: `_blank`: Abre o link em uma nova janela `_parent`: Abre o link no frame pai `_self`: Padrão. Abre o link no frame atual `_top`: Abre o link na janela inteira Nota: Esta propriedade só é válida quando o atributo `href` está definido.
rel	rel	true	'alternate' \| 'author' \| 'bookmark' \| 'external' \| 'help' \| 'license' \| 'me' \| 'next' \| 'nofollow' \| 'noreferrer' \| 'opener' \| 'prev' \| 'search' \| 'tag'		A relação entre o documento atual e o documento vinculado. Os valores possíveis são: `alternate`: Versão alternativa do documento atual `author`: Autor do documento atual ou artigo `bookmark`: Link permanente para a seção ancestral mais próxima `external`: O documento referenciado não está no mesmo site do documento atual `help`: Link para documentação de ajuda relacionada `license`: O conteúdo principal do documento atual está coberto pela licença de direitos autorais do arquivo referenciado `me`: O documento atual representa o proprietário do conteúdo vinculado `next`: O documento atual faz parte de uma série, e o documento referenciado é o próximo da série `nofollow`: O autor ou editor do documento atual não endossa o arquivo referenciado `noreferrer`: Não inclui o cabeçalho `Referer`. Tem efeito semelhante ao `noopener` `opener`: Se o hiperlink criar um contexto de navegação de nível superior (ou seja, o valor do atributo `target` for `_blank`), cria um contexto de navegação auxiliar `prev`: O documento atual faz parte de uma série, e o documento referenciado é o anterior da série `search`: Fornece um link para um recurso que pode ser usado para pesquisar o arquivo atual e suas páginas relacionadas `tag`: Fornece uma tag (identificada pelo endereço fornecido) aplicável ao documento atual Nota: Disponível apenas quando o atributo `href` é especificado.
autofocus	autofocus	true	boolean	false	Define se o elemento deve receber foco automaticamente após o carregamento da página.
tabindex	tabIndex	false	number		A ordem do elemento ao navegar com a tecla Tab.

### Métodos

Nome Descrição

click(): void

Simula um clique do mouse no elemento.

focus(options?: FocusOptions): void

Define o foco no elemento atual.

Você pode passar um objeto como argumento, com as seguintes propriedades:

preventScroll: 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 true.

blur(): void

Remove o foco do elemento atual.

### Eventos

Nome	Descrição
focus	Disparado ao receber foco.
blur	Disparado ao perder o foco.

### Slots

Nome	Descrição
(padrão)	Texto do item de navegação.
icon	Ícone.
active-icon	Elemento de ícone no estado ativo.
badge	Badge.

### CSS Parts

Nome	Descrição
container	Contêiner do item de navegação.
indicator	Indicador.
badge	Badge.
icon	Ícone.
active-icon	Ícone no estado ativo.
label	Texto do item de navegação.

### Propriedades CSS personalizadas

Nome	Descrição
--shape-corner-indicator	Tamanho da borda arredondada do indicador. Pode ser um valor em pixels, mas é recomendado usar os design tokens.

## mdui-navigation-bar API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
hide	hide	true	boolean	false	Define se o componente está oculto.
label-visibility	labelVisibility	true	'auto' \| 'selected' \| 'labeled' \| 'unlabeled'	'auto'	Estado de visibilidade do texto. Os valores possíveis são: `auto`: Quando o número de itens é menor ou igual a 3, o texto é sempre exibido; quando é maior que 3, apenas o texto do item selecionado é exibido. `selected`: Exibe o texto apenas no estado selecionado. `labeled`: Sempre exibe o texto. `unlabeled`: Nunca exibe o texto.
value	value	true	string		O valor do `<mdui-navigation-bar-item>` atualmente selecionado.
scroll-behavior	scrollBehavior	true	'hide' \| 'shrink' \| 'elevate'		Comportamento de rolagem. O valor possível é: `hide`: Ocultar ao rolar.
scroll-target	scrollTarget	false	string \| HTMLElement \| JQ<HTMLElement>		O elemento no qual o evento de rolagem será monitorado. O valor pode ser um seletor CSS, um elemento DOM ou um objeto JQ. Por padrão, monitora o evento de rolagem da `window`.
scroll-threshold	scrollThreshold	true	number		A distância de rolagem, em `px`, necessária para acionar o comportamento.
order	order	true	number		A ordem de layout deste componente dentro do `<mdui-layout>`, em ordem crescente. O valor padrão é `0`.

### Eventos

Nome	Descrição
change	Disparado quando o valor muda.
show	Disparado quando o componente começa a ser exibido. Pode impedir a exibição chamando `event.preventDefault()`.
shown	Disparado quando a animação de exibição é concluída.
hide	Disparado quando o componente começa a ser ocultado. Pode impedir a ocultação chamando `event.preventDefault()`.
hidden	Disparado quando a animação de ocultação é concluída.

### Slots

Nome	Descrição
(padrão)	Componentes `<mdui-navigation-bar-item>`.

### Propriedades CSS personalizadas

Nome	Descrição
--shape-corner	Tamanho da borda arredondada do componente. Pode ser um valor em pixels, mas é recomendado usar os design tokens.
--z-index	Valor CSS `z-index` do componente.

# Componente NavigationDrawer A gaveta de navegação é usada para fornecer navegação na lateral da página, permitindo que os usuários acessem rapidamente diferentes páginas ou conteúdos. Normalmente, você pode usar o componente [``](/pt-br/docs/2/components/list) dentro da gaveta de navegação para adicionar itens de navegação. ## Como usar {#usage} Importe o componente conforme necessário: ```js import 'mdui/components/navigation-drawer.js'; ``` Importe o tipo TypeScript do componente conforme necessário: ```ts import type { NavigationDrawer } from 'mdui/components/navigation-drawer.js'; ``` Exemplo de uso: ```html

Fechar gaveta de navegação

Abrir gaveta de navegação

``` **Observações:** Este componente usa `position: fixed` por padrão. Quando `modal` é `false` e a largura da viewport é maior ou igual a [`--mdui-breakpoint-md`](/pt-br/docs/2/styles/design-tokens#breakpoint), ele adiciona automaticamente `padding-left` ou `padding-right` ao `body` para evitar que o conteúdo da página seja ocultado pelo componente. No entanto, nos dois casos a seguir, ele usará `position: absolute` por padrão: 1. Quando o atributo `contained` é `true`. 2. Quando o componente está dentro de [``](/pt-br/docs/2/components/layout). Assim, nenhum `padding-left` ou `padding-right` será adicionado. ## Exemplos {#examples} ### Dentro de um contêiner especificado {#example-contained} Por padrão, a gaveta de navegação é exibida no lado esquerdo ou direito da página, em relação à janela atual. Se você deseja colocar a gaveta de navegação dentro de um contêiner especificado, adicione o atributo `contained`. Assim, a gaveta será exibida em relação ao elemento pai (você precisa adicionar os estilos `position: relative; overflow: hidden;` ao elemento pai). ```html

Fechar gaveta de navegação

Abrir gaveta de navegação

``` ### Modal {#example-modal} Use o atributo `modal` para exibir uma sobreposição ao abrir a gaveta de navegação. Observe que quando a largura da janela ou do elemento pai for menor que [`--mdui-breakpoint-md`](/pt-br/docs/2/styles/design-tokens#breakpoint), este parâmetro é ignorado e a sobreposição sempre será exibida. Use o atributo `close-on-esc` para fechar a gaveta de navegação ao pressionar a tecla ESC. Use o atributo `close-on-overlay-click` para fechar a gaveta de navegação ao clicar na sobreposição. ```html ``` ### No lado direito {#example-placement} Defina o atributo `placement` como `right` para exibir a gaveta de navegação no lado direito da página. ```html

Fechar gaveta de navegação

Abrir gaveta de navegação

``` ## mdui-navigation-drawer API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
open	open	true	boolean	false	Define se a gaveta de navegação está aberta.
modal	modal	true	boolean	false	Define se uma camada de sobreposição deve ser exibida quando a gaveta de navegação está aberta. Em dispositivos com tela estreita (largura da tela menor que `--mdui-breakpoint-md`), a camada de sobreposição é sempre exibida, ignorando este parâmetro.
close-on-esc	closeOnEsc	true	boolean	false	Define se, quando há uma camada de sobreposição, pressionar a tecla ESC deve fechar a gaveta de navegação.
close-on-overlay-click	closeOnOverlayClick	true	boolean	false	Define se clicar na camada de sobreposição deve fechar a gaveta de navegação.
placement	placement	true	'left' \| 'right'	'left'	Posição da gaveta de navegação. Os valores possíveis são: `left`: Esquerda. `right`: Direita.
contained	contained	true	boolean	false	Por padrão, a gaveta de navegação é exibida em relação ao elemento `body`. Quando esta propriedade é definida como `true`, a gaveta de navegação será exibida em relação ao seu elemento pai. Nota: Ao definir esta propriedade, deve-se definir manualmente o estilo `position: relative; overflow: hidden;` no elemento pai.
order	order	true	number		A ordem de layout deste componente dentro do `<mdui-layout>`, em ordem crescente. O valor padrão é `0`.

### Eventos

Nome	Descrição
open	Disparado antes de a gaveta de navegação abrir. Pode impedir a abertura chamando `event.preventDefault()`.
opened	Disparado após a conclusão da animação de abertura da gaveta de navegação.
close	Disparado antes de a gaveta de navegação fechar. Pode impedir o fechamento chamando `event.preventDefault()`.
closed	Disparado após a conclusão da animação de fechamento da gaveta de navegação.
overlay-click	Disparado ao clicar na camada de sobreposição.

### Slots

Nome	Descrição
(padrão)	Conteúdo dentro da gaveta de navegação.

### CSS Parts

Nome	Descrição
overlay	Camada de sobreposição.
panel	Contêiner da gaveta de navegação.

### Propriedades CSS personalizadas

Nome	Descrição
--shape-corner	Tamanho da borda arredondada do componente. Pode ser um valor em pixels, mas é recomendado usar os design tokens.
--z-index	Valor CSS `z-index` do componente.

# Componente NavigationRail O trilho de navegação fornece acesso a diferentes páginas principais para tablets e computadores desktop. ## Como usar {#usage} Importe os componentes conforme necessário: ```js import 'mdui/components/navigation-rail.js'; import 'mdui/components/navigation-rail-item.js'; ``` Importe os tipos TypeScript dos componentes conforme necessário: ```ts import type { NavigationRail } from 'mdui/components/navigation-rail.js'; import type { NavigationRailItem } from 'mdui/components/navigation-rail-item.js'; ``` Exemplo de uso: (o `style="position: relative"` no exemplo é apenas para fins de demonstração; remova este estilo ao usar.) ```html

Recent

Images

Library

``` **Observações:** Este componente usa `position: fixed` por padrão e adiciona automaticamente `padding-left` ou `padding-right` ao `body` para evitar que o conteúdo da página seja ocultado pelo componente. No entanto, nos dois casos a seguir, ele usará `position: absolute` por padrão: 1. Quando o atributo `contained` do componente `` é `true`. Assim, `padding-left` ou `padding-right` será adicionado ao elemento pai. 2. Quando o componente está dentro de [``](/pt-br/docs/2/components/layout). Assim, nenhum `padding-left` ou `padding-right` será adicionado. ## Exemplos {#examples} ### Dentro de um contêiner especificado {#example-contained} Por padrão, o trilho de navegação é exibido no lado esquerdo ou direito da página, em relação à janela atual. Se você deseja colocar o trilho de navegação dentro de um contêiner especificado, adicione o atributo `contained` ao componente ``. Assim, o trilho será exibido em relação ao seu elemento pai (você precisa adicionar o estilo `position: relative` ao elemento pai). ```html

Recent

Images

Library

Conteúdo da página

``` ### No lado direito {#example-placement} Defina o atributo `placement` como `right` no componente `` para exibir o trilho de navegação no lado direito. ```html

Recent

Images

Library

Conteúdo da página

``` ### Exibir divisor {#example-divider} Use o atributo `divider` ao componente `` para adicionar uma linha divisória no trilho de navegação, a fim de distinguir do conteúdo da página. ```html

Recent

Images

Library

Conteúdo da página

``` ### Adicionar elementos no topo/rodapé {#example-top-bottom} Dentro do componente ``, você pode adicionar elementos pelos slots `top` e `bottom` para adicionar elementos no topo e no rodapé. ```html

Recent

Images

Library

Conteúdo da página

``` ### Alinhamento vertical dos itens de navegação {#example-alignment} Defina o atributo `alignment` do componente `` para modificar o alinhamento vertical dos itens de navegação. ```html

Recent

Images

Library

start

center

end

``` ### Ícone {#example-icon} No componente ``, use o atributo `icon` para definir o ícone do item de navegação no estado inativo e o atributo `active-icon` para definir o ícone no estado ativo. Você também pode usar os slots `icon` e `active-icon` para definir os elementos de ícone dos estados inativo e ativo. ```html

Recent

Images

Library

Conteúdo da página

``` ### Apenas ícone {#example-no-label} O componente `` pode ser usado apenas com ícone, sem texto. ```html

Conteúdo da página

Recent

Images

Library

Conteúdo da página

``` ### Badge {#example-badge} No componente ``, você pode adicionar um badge pelo slot `badge`. ```html

Recent 99+

Images

Library

Conteúdo da página

``` ## mdui-navigation-rail-item API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
icon	icon	true	string		Nome do ícone Material Icons para o estado inativo. Também pode ser definido via `slot="icon"`.
active-icon	activeIcon	true	string		Nome do ícone Material Icons para o estado ativo. Também pode ser definido via `slot="active-icon"`.
value	value	true	string		O valor do item de navegação.
href	href	true	string		A URL de destino do link. Ao definir esta propriedade, o componente será renderizado internamente como um elemento `<a>` e poderá usar atributos de link.
download	download	true	string		O nome do arquivo para download. Nota: Esta propriedade só é válida quando o atributo `href` está definido.
target	target	true	'_blank' \| '_parent' \| '_self' \| '_top'		Define como o link será aberto. Os valores possíveis são: `_blank`: Abre o link em uma nova janela `_parent`: Abre o link no frame pai `_self`: Padrão. Abre o link no frame atual `_top`: Abre o link na janela inteira Nota: Esta propriedade só é válida quando o atributo `href` está definido.
rel	rel	true	'alternate' \| 'author' \| 'bookmark' \| 'external' \| 'help' \| 'license' \| 'me' \| 'next' \| 'nofollow' \| 'noreferrer' \| 'opener' \| 'prev' \| 'search' \| 'tag'		A relação entre o documento atual e o documento vinculado. Os valores possíveis são: `alternate`: Versão alternativa do documento atual `author`: Autor do documento atual ou artigo `bookmark`: Link permanente para a seção ancestral mais próxima `external`: O documento referenciado não está no mesmo site do documento atual `help`: Link para documentação de ajuda relacionada `license`: O conteúdo principal do documento atual está coberto pela licença de direitos autorais do arquivo referenciado `me`: O documento atual representa o proprietário do conteúdo vinculado `next`: O documento atual faz parte de uma série, e o documento referenciado é o próximo da série `nofollow`: O autor ou editor do documento atual não endossa o arquivo referenciado `noreferrer`: Não inclui o cabeçalho `Referer`. Tem efeito semelhante ao `noopener` `opener`: Se o hiperlink criar um contexto de navegação de nível superior (ou seja, o valor do atributo `target` for `_blank`), cria um contexto de navegação auxiliar `prev`: O documento atual faz parte de uma série, e o documento referenciado é o anterior da série `search`: Fornece um link para um recurso que pode ser usado para pesquisar o arquivo atual e suas páginas relacionadas `tag`: Fornece uma tag (identificada pelo endereço fornecido) aplicável ao documento atual Nota: Disponível apenas quando o atributo `href` é especificado.
autofocus	autofocus	true	boolean	false	Define se o elemento deve receber foco automaticamente após o carregamento da página.
tabindex	tabIndex	false	number		A ordem do elemento ao navegar com a tecla Tab.

### Métodos

Nome Descrição

click(): void

Simula um clique do mouse no elemento.

focus(options?: FocusOptions): void

Define o foco no elemento atual.

Você pode passar um objeto como argumento, com as seguintes propriedades:

preventScroll: 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 true.

blur(): void

Remove o foco do elemento atual.

### Eventos

Nome	Descrição
focus	Disparado ao receber foco.
blur	Disparado ao perder o foco.

### Slots

Nome	Descrição
(padrão)	Conteúdo de texto.
icon	Ícone.
active-icon	Ícone no estado ativo.
badge	Badge.

### CSS Parts

Nome	Descrição
container	Contêiner do item de navegação.
indicator	Indicador.
badge	Badge.
icon	Ícone.
active-icon	Ícone no estado ativo.
label	Conteúdo de texto.

### Propriedades CSS personalizadas

Nome	Descrição
--shape-corner-indicator	Tamanho da borda arredondada do indicador. Pode ser um valor em pixels, mas é recomendado usar os design tokens.

## mdui-navigation-rail API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
value	value	true	string		O valor do `<mdui-navigation-rail-item>` atualmente selecionado.
placement	placement	true	'left' \| 'right'	'left'	Posição da barra de navegação. Os valores possíveis são: `left`: Esquerda. `right`: Direita.
alignment	alignment	true	'start' \| 'center' \| 'end'	'start'	Alinhamento dos elementos `<mdui-navigation-rail-item>`. Os valores possíveis são: `start`: Alinhado ao topo. `center`: Alinhado ao centro. `end`: Alinhado à base.
contained	contained	true	boolean	false	Por padrão, a barra de navegação é exibida em relação ao elemento `body`. Quando esta propriedade é definida como `true`, a barra de navegação será exibida em relação ao seu elemento pai. Nota: Ao definir esta propriedade, deve-se definir manualmente o estilo `position: relative;` no elemento pai.
divider	divider	true	boolean	false	Define se uma linha divisória deve ser adicionada entre a barra de navegação e o conteúdo da página.
order	order	true	number		A ordem de layout deste componente dentro do `<mdui-layout>`, em ordem crescente. O valor padrão é `0`.

### Eventos

Nome	Descrição
change	Disparado quando o valor muda.

### Slots

Nome	Descrição
(padrão)	Componentes `<mdui-navigation-rail-item>`.
top	Elementos no topo.
bottom	Elementos na base.

### CSS Parts

Nome	Descrição
top	Contêiner dos elementos do topo.
bottom	Contêiner dos elementos da base.
items	Contêiner dos componentes `<mdui-navigation-rail-item>`.

### Propriedades CSS personalizadas

Nome	Descrição
--shape-corner	Tamanho da borda arredondada do componente. Pode ser um valor em pixels, mas é recomendado usar os design tokens.
--z-index	Valor CSS `z-index` do componente.

# Componente Radio Radio permite que os usuários selecionem uma opção de um conjunto, garantindo que apenas uma opção seja selecionada por vez. ## Como usar {#usage} Importe os componentes conforme necessário: ```js import 'mdui/components/radio-group.js'; import 'mdui/components/radio.js'; ``` Importe os tipos TypeScript dos componentes conforme necessário: ```ts import type { RadioGroup } from 'mdui/components/radio-group.js'; import type { Radio } from 'mdui/components/radio.js'; ``` Exemplo de uso: ```html

Chinese

English

``` ## Exemplos {#examples} ### Estado selecionado {#example-checked} O valor do atributo `value` do componente `` é o valor `value` do componente `` atualmente selecionado. Você também pode alternar o radio selecionado atualizando o atributo `value` do componente ``. ```html

Chinese

English

``` Você pode usar o componente `` isoladamente. Assim, você pode ler e modificar o estado selecionado pelo atributo `checked`. ```html Radio ``` ### Estado desabilitado {#example-disabled} Use o atributo `disabled` no componente `` para desabilitar todo o grupo de radios. ```html

Chinese

English

``` Para desabilitar um radio específico, adicione o atributo `disabled` no componente ``. ```html

Chinese

English

``` ### Ícone {#example-icon} Você pode definir os atributos `unchecked-icon` e `checked-icon` para definir os ícones do Material Icons nos estados não selecionado e selecionado, respectivamente. Você também pode usar os slots `unchecked-icon` e `checked-icon` para definir os ícones. ```html

Chinese

English

``` ## mdui-radio-group API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
disabled	disabled	true	boolean	false	Define se este componente está desabilitado.
form	form	true	string		O elemento `<form>` associado. O valor deste atributo deve ser o `id` de um elemento `<form>` na mesma página. Se este atributo não for especificado, o elemento precisa ser um elemento filho de um `<form>`. Com este atributo, você pode colocar o elemento em qualquer lugar da página, não apenas como filho do elemento `<form>`.
name	name	true	string	''	O nome do grupo de botões de opção, que será enviado com os dados do formulário.
value	value	true	string	''	O valor atualmente selecionado no grupo de botões de opção, que será enviado com os dados do formulário.
undefined	defaultValue	false	string	''	O valor selecionado por padrão. Ao redefinir o formulário, será restaurado para este valor padrão. Esta propriedade só pode ser definida via propriedade JavaScript.
required	required	true	boolean	false	Define se, ao enviar o formulário, é obrigatório que um dos botões de opção esteja selecionado.
undefined	validity	false	ValidityState		Objeto que representa o estado de validação do formulário. Consulte `ValidityState` para mais detalhes.
undefined	validationMessage	false	string		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.

### Métodos

Nome Descrição

checkValidity(): boolean

Verifica se o campo do formulário passou na validação. Se não passou, retorna false e dispara o evento invalid; se passou, retorna true.

reportValidity(): boolean

Verifica se o campo do formulário passou na validação. Se não passou, retorna false e dispara o evento invalid; se passou, retorna true.

Se a validação falhar, também exibe uma mensagem de erro no componente.

setCustomValidity(message: string): void

Define um texto de erro personalizado. Enquanto este texto não estiver vazio, indica que o campo não passou na validação.

### Eventos

Nome	Descrição
change	Disparado quando o valor selecionado muda.
input	Disparado quando o valor selecionado muda.
invalid	Disparado quando a validação do campo do formulário falha.

### Slots

Nome	Descrição
(padrão)	Elementos `<mdui-radio>`.

## mdui-radio API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
value	value	true	string	''	O valor atual do botão de opção.
disabled	disabled	true	boolean	false	Define se o botão de opção atual está desabilitado.
checked	checked	true	boolean	false	Define se o botão de opção atual está selecionado.
unchecked-icon	uncheckedIcon	true	string		Nome do ícone Material Icons para o estado não selecionado. Também pode ser definido via `slot="unchecked-icon"`.
checked-icon	checkedIcon	true	string		Nome do ícone Material Icons para o estado selecionado. Também pode ser definido via `slot="checked-icon"`.
autofocus	autofocus	true	boolean	false	Define se o elemento deve receber foco automaticamente após o carregamento da página.
tabindex	tabIndex	false	number		A ordem do elemento ao navegar com a tecla Tab.

### Métodos

Nome Descrição

click(): void

Simula um clique do mouse no elemento.

focus(options?: FocusOptions): void

Define o foco no elemento atual.

Você pode passar um objeto como argumento, com as seguintes propriedades:

preventScroll: 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 true.

blur(): void

Remove o foco do elemento atual.

### Eventos

Nome	Descrição
focus	Disparado ao receber foco.
blur	Disparado ao perder o foco.
change	Disparado quando este botão de opção é selecionado.

### Slots

Nome	Descrição
(padrão)	Conteúdo de texto.
unchecked-icon	Ícone do estado não selecionado.
checked-icon	Ícone do estado selecionado.

### CSS Parts

Nome	Descrição
control	Contêiner do ícone esquerdo.
unchecked-icon	Ícone do estado não selecionado.
checked-icon	Ícone do estado selecionado.
label	Conteúdo de texto.

# Componente RangeSlider O slider de intervalo permite que os usuários selecionem um intervalo de valores em uma escala. ## Como usar {#usage} Importe o componente conforme necessário: ```js import 'mdui/components/range-slider.js'; ``` Importe o tipo TypeScript do componente conforme necessário: ```ts import type { RangeSlider } from 'mdui/components/range-slider.js'; ``` Exemplo de uso: ```html ``` ## Exemplos {#examples} ### Valor padrão {#example-value} Através do atributo `value`, você pode ler ou definir o valor atual do slider de intervalo. Este atributo é um array e só pode ser lido e definido por propriedades JavaScript. ```html ``` ### Estado desabilitado {#example-disabled} Use o atributo `disabled` para desabilitar o slider de intervalo. ```html ``` ### Intervalo {#example-min-max} Use os atributos `min` e `max` para definir o valor mínimo e máximo do slider de intervalo. ```html ``` ### Incremento {#example-step} Use o atributo `step` para definir o incremento do slider de intervalo. ```html ``` ### Marcas de graduação {#example-tickmarks} Use o atributo `tickmarks` para adicionar marcas de graduação no slider de intervalo. ```html ``` ### Ocultar dica de texto {#example-nolabel} Use o atributo `nolabel` para ocultar a dica de texto no slider de intervalo. ```html ``` ### Modificar a dica de texto {#example-labelFormatter} Através da propriedade JavaScript `labelFormatter`, você pode modificar o formato da dica de texto. Esta propriedade é uma função que recebe o valor atual do slider de intervalo como parâmetro e retorna o texto que você deseja exibir. ```html ``` ## mdui-range-slider API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
undefined	defaultValue	false	number[]	[]	Valor padrão. Ao redefinir o formulário, será restaurado para este valor padrão. Esta propriedade só pode ser definida via propriedade JavaScript.
undefined	value	false	number[]		O valor do slider, no formato de array, que será enviado com os dados do formulário. NOTA: Esta propriedade não pode ter um valor inicial definido via atributo HTML. Para modificar este valor, é necessário alterar a propriedade JavaScript.
autofocus	autofocus	true	boolean	false	Define se o elemento deve receber foco automaticamente após o carregamento da página.
tabindex	tabIndex	false	number		A ordem do elemento ao navegar com a tecla Tab.
min	min	true	number	0	O valor mínimo do slider. O padrão é `0`.
max	max	true	number	100	O valor máximo do slider. O padrão é `100`.
step	step	true	number	1	O intervalo de incremento. O padrão é `1`.
tickmarks	tickmarks	true	boolean	false	Define se devem ser adicionadas marcas de escala.
nolabel	nolabel	true	boolean	false	Define se o texto do rótulo deve ser ocultado.
disabled	disabled	true	boolean	false	Define se o componente está desabilitado.
form	form	true	string		O elemento `<form>` associado. O valor deste atributo deve ser o `id` de um elemento `<form>` na mesma página. Se este atributo não for especificado, o elemento precisa ser um elemento filho de um `<form>`. Com este atributo, você pode colocar o elemento em qualquer lugar da página, não apenas como filho do elemento `<form>`.
name	name	true	string	''	O nome do slider, que será enviado com os dados do formulário.
undefined	validity	false	ValidityState		Objeto que representa o estado de validação do formulário. Consulte `ValidityState` para mais detalhes.
undefined	validationMessage	false	string		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.
undefined	labelFormatter	false	(value: number) => string		Função usada para personalizar o formato de exibição do rótulo. O parâmetro da função é o valor atual do slider, e o valor de retorno é o texto que se deseja exibir.

### Métodos

Nome	Descrição
click(): void	Simula um clique do mouse no elemento.
focus(options?: FocusOptions): void	Define o foco no elemento atual. Você pode passar um objeto como argumento, com as seguintes propriedades: `preventScroll`: 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 `true`.
blur(): void	Remove o foco do elemento atual.
checkValidity(): boolean	Verifica se o campo do formulário passou na validação. Se não passou, retorna `false` e dispara o evento `invalid`; se passou, retorna `true`.
reportValidity(): boolean	Verifica se o campo do formulário passou na validação. Se não passou, retorna `false` e dispara o evento `invalid`; se passou, retorna `true`. Se a validação falhar, também exibe uma mensagem de erro no componente.
setCustomValidity(message: string): void	Define um texto de erro personalizado. Enquanto este texto não estiver vazio, indica que o campo não passou na validação.

### Eventos

Nome	Descrição
focus	Disparado ao receber foco.
blur	Disparado ao perder o foco.
change	Disparado quando o valor muda e o elemento perde o foco.
input	Disparado quando o valor muda.
invalid	Disparado quando a validação do campo do formulário falha.

### CSS Parts

Nome	Descrição
track-inactive	Trilha do estado inativo.
track-active	Trilha do estado ativo.
handle	Alça de controle.
label	Texto do rótulo.
tickmark	Marca de escala.

# Componente Select O campo de seleção suspensa fornece várias opções em um menu suspenso, facilitando a seleção rápida do conteúdo desejado pelo usuário. Esta página descreve principalmente o uso do componente ``. Para o uso dos itens do menu suspenso, consulte [``](/pt-br/docs/2/components/menu#menu-item-api). ## Como usar {#usage} Importe os componentes conforme necessário: ```js import 'mdui/components/select.js'; import 'mdui/components/menu-item.js'; ``` Importe os tipos TypeScript dos componentes conforme necessário: ```ts import type { Select } from 'mdui/components/select.js'; import type { MenuItem } from 'mdui/components/menu-item.js'; ``` Exemplo de uso: ```html

Item 1

Item 2

``` ## Exemplos {#examples} ### Forma {#example-variant} Use o atributo `variant` para definir a forma do campo de seleção. ```html

Item 1

Item 2

Item 1

Item 2

``` ### Suporte a seleção múltipla {#example-multiple} O campo de seleção é de seleção única por padrão; o valor `value` do componente `` é o valor `value` do [``](/pt-br/docs/2/components/menu#menu-item-api) atualmente selecionado. Use o atributo `multiple` para permitir a seleção múltipla. Assim, o valor `value` do `` será um array dos valores `value` dos [``](/pt-br/docs/2/components/menu#menu-item-api) atualmente selecionados. Nota: No modo de seleção múltipla, o valor `value` do `` é um array e só pode ser lido e definido por propriedades JavaScript. ```html

Item 1

Item 2

Item 3

``` ### Texto auxiliar {#example-helper-text} Use o atributo `label` para definir o texto do rótulo acima do campo de seleção. ```html

Item 1

Item 2

``` Use o atributo `placeholder` para definir o texto de espaço reservado quando nenhum valor está selecionado. ```html

Item 1

Item 2

``` Use o atributo `helper` para definir o texto de ajuda na parte inferior do campo de seleção. Você também pode usar o slot `helper` para definir o texto de ajuda. ```html

Item 1

Item 2

Item 1

Item 2

Supporting text ``` ### Modo somente leitura {#example-readonly} Use o atributo `readonly` para colocar o campo de seleção no modo somente leitura. ```html

Item 1

Item 2

``` ### Modo desabilitado {#example-disabled} Use o atributo `disabled` para desabilitar o campo de seleção. ```html

Item 1

Item 2

``` ### Com limpeza {#example-clearable} Use o atributo `clearable` para que, quando o campo de seleção tiver um valor, um botão de limpeza apareça no lado direito. ```html

Item 1

Item 2

``` Você também pode personalizar o botão de limpeza pelo slot `clear`. ```html

Item 1

Item 2

``` ### Posição do menu suspenso {#example-placement} Use o atributo `placement` para definir a posição do menu suspenso. ```html

Item 1

Item 2

``` ### Texto alinhado à direita {#example-end-aligned} Use o atributo `end-aligned` para alinhar o texto à direita. ```html

Item 1

Item 2

``` ### Texto e ícones antes/depois {#example-prefix-suffix} Defina os atributos `icon` e `end-icon` para adicionar ícones do Material Icons à esquerda e à direita do campo de seleção. Você também pode adicionar elementos pelos slots `icon` e `end-icon`. ```html

Item 1

Item 2

Item 1

Item 2

``` Defina os atributos `prefix` e `suffix` para adicionar texto à esquerda e à direita do campo de seleção. Esses textos só são exibidos quando o campo de seleção está em foco ou tem um valor. Você também pode usar os slots `prefix` e `suffix` para adicionar elementos de texto. ```html

Item 1

Item 2

Item 1

Item 2

$ /100 ``` ## mdui-select API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
variant	variant	true	'filled' \| 'outlined'	'filled'	Estilo do campo de seleção. Os valores possíveis são: `filled`: Campo de seleção com cor de fundo; efeito visual mais forte. `outlined`: Campo de seleção com borda; efeito visual mais suave.
multiple	multiple	true	boolean	false	Define se suporta seleção múltipla.
name	name	true	string	''	O nome do campo de seleção, que será enviado com os dados do formulário.
value	value	false	string \| string[]	''	O valor do campo de seleção, que será enviado com os dados do formulário. Se o atributo `multiple` não for especificado, este valor é uma string; se o atributo `multiple` for especificado, este valor é um array de strings. O atributo HTML só pode definir valores string; para definir um valor de array, defina via propriedade JavaScript.
undefined	defaultValue	false	string \| string[]	''	O valor selecionado por padrão. Ao redefinir o formulário, será restaurado para este valor padrão. Esta propriedade só pode ser definida via propriedade JavaScript.
label	label	true	string		Texto do rótulo.
placeholder	placeholder	true	string		Texto de placeholder.
helper	helper	true	string		Texto de ajuda na parte inferior do campo de seleção. Também pode ser definido via `slot="helper"`.
clearable	clearable	true	boolean	false	Define se o campo de seleção pode ser limpo.
clear-icon	clearIcon	true	string		Nome do ícone Material Icons para o botão de limpar, exibido à direita do campo de seleção quando ele é limpável. Também pode ser definido via `slot="clear-icon"`.
placement	placement	true	'auto' \| 'bottom' \| 'top'	'auto'	Posição do campo de seleção. Os valores possíveis são: `auto`: Posição automática. `bottom`: Localizada abaixo. `top`: Localizada acima.
end-aligned	endAligned	true	boolean	false	Define se o texto deve ser alinhado à direita.
prefix	prefix	true	string		Texto de prefixo do campo de seleção. Exibido apenas no estado de foco ou quando o campo de seleção tem valor. Também pode ser definido via `slot="prefix"`.
suffix	suffix	true	string		Texto de sufixo do campo de seleção. Exibido apenas no estado de foco ou quando o campo de seleção tem valor. Também pode ser definido via `slot="suffix"`.
icon	icon	true	string		Nome do ícone Material Icons para o ícone de prefixo do campo de seleção. Também pode ser definido via `slot="icon"`.
end-icon	endIcon	true	string		Nome do ícone Material Icons para o ícone de sufixo do campo de seleção. Também pode ser definido via `slot="end-icon"`.
error-icon	errorIcon	true	string		Nome do ícone Material Icons exibido à direita do campo de seleção quando a validação do campo do formulário falha. Também pode ser definido via `slot="error-icon"`.
form	form	true	string		O elemento `<form>` associado. O valor deste atributo deve ser o `id` de um elemento `<form>` na mesma página. Se este atributo não for especificado, o elemento precisa ser um elemento filho de um `<form>`. Com este atributo, você pode colocar o elemento em qualquer lugar da página, não apenas como filho do elemento `<form>`.
readonly	readonly	true	boolean	false	Define se o componente está no estado somente leitura.
disabled	disabled	true	boolean	false	Define se o componente está desabilitado.
required	required	true	boolean	false	Define se, ao enviar o formulário, é obrigatório que este campo seja preenchido.
undefined	validity	false	ValidityState		Objeto que representa o estado de validação do formulário. Consulte `ValidityState` para mais detalhes.
undefined	validationMessage	false	string		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.
autofocus	autofocus	true	boolean	false	Define se o elemento deve receber foco automaticamente após o carregamento da página.
tabindex	tabIndex	false	number		A ordem do elemento ao navegar com a tecla Tab.

### Métodos

Nome	Descrição
checkValidity(): boolean	Verifica se o campo do formulário passou na validação. Se não passou, retorna `false` e dispara o evento `invalid`; se passou, retorna `true`.
reportValidity(): boolean	Verifica se o campo do formulário passou na validação. Se não passou, retorna `false` e dispara o evento `invalid`; se passou, retorna `true`. Se a validação falhar, também exibe uma mensagem de erro no componente.
setCustomValidity(message: string): void	Define um texto de erro personalizado. Enquanto este texto não estiver vazio, indica que o campo não passou na validação.
click(): void	Simula um clique do mouse no elemento.
focus(options?: FocusOptions): void	Define o foco no elemento atual. Você pode passar um objeto como argumento, com as seguintes propriedades: `preventScroll`: 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 `true`.
blur(): void	Remove o foco do elemento atual.

### Eventos

Nome	Descrição
focus	Disparado ao receber foco.
blur	Disparado ao perder o foco.
change	Disparado quando o valor selecionado muda.
invalid	Disparado quando a validação do campo do formulário falha.
clear	Disparado ao clicar no botão de limpar gerado pelo atributo `clearable`. Pode impedir a limpeza do campo de seleção chamando `event.preventDefault()`.

### Slots

Nome	Descrição
(padrão)	Elementos `<mdui-menu-item>`.
icon	Ícone à esquerda.
end-icon	Ícone à direita.
error-icon	Ícone à direita no estado de falha de validação.
prefix	Texto à esquerda.
suffix	Texto à direita.
clear-button	Botão de limpar.
clear-icon	Ícone dentro do botão de limpar.
helper	Texto de ajuda na parte inferior.

### CSS Parts

Nome	Descrição
chips	Contêiner para os chips dos valores selecionados no modo múltiplo.
chip	Chip para cada valor selecionado no modo múltiplo.
chip__button	Elemento `<button>` dentro do chip.
chip__label	Texto dentro do chip.
chip__delete-icon	Ícone de exclusão dentro do chip.
text-field	Campo de texto, ou seja, o elemento `<mdui-text-field>`.
text-field__container	Contêiner do campo de texto dentro do text-field.
text-field__icon	Ícone à esquerda dentro do text-field.
text-field__end-icon	Ícone à direita dentro do text-field.
text-field__error-icon	Ícone à direita no estado de falha de validação dentro do text-field.
text-field__prefix	Texto à esquerda dentro do text-field.
text-field__suffix	Texto à direita dentro do text-field.
text-field__label	Texto do rótulo dentro do text-field.
text-field__input	Elemento `<input>` dentro do text-field.
text-field__clear-button	Botão de limpar dentro do text-field.
text-field__clear-icon	Ícone dentro do botão de limpar do text-field.
text-field__supporting	Contêiner de informações auxiliares na parte inferior do text-field, incluindo helper e error.
text-field__helper	Texto de ajuda na parte inferior dentro do text-field.
text-field__error	Texto de descrição de erro na parte inferior dentro do text-field.
menu	Menu suspenso, ou seja, o elemento `<mdui-menu>`.

# Componente SegmentedButton O componente de botão segmentado encapsula um grupo de botões, usado para fornecer opções, alternar visualizações ou ordenar elementos, entre outros. ## Como usar {#usage} Importe os componentes conforme necessário: ```js import 'mdui/components/segmented-button-group.js'; import 'mdui/components/segmented-button.js'; ``` Importe os tipos TypeScript dos componentes conforme necessário: ```ts import type { SegmentedButtonGroup } from 'mdui/components/segmented-button-group.js'; import type { SegmentedButton } from 'mdui/components/segmented-button.js'; ``` Exemplo de uso: ```html

Day

Week

Month

``` ## Exemplos {#examples} ### Largura total {#example-full-width} Use o atributo `full-width` no elemento `` para fazer o componente ocupar toda a largura. ```html

Day

Week

Month

``` ### Modo de seleção única {#example-selects-single} Defina o atributo `selects` como `single` no elemento `` para habilitar o modo de seleção única. Assim, o valor do atributo `value` do `` será o valor `value` do `` atualmente selecionado. ```html

Day

Week

Month

Day

Week

Month

``` ### Modo de seleção múltipla {#example-selects-multiple} Defina o atributo `selects` como `multiple` no elemento `` para habilitar o modo de seleção múltipla. Assim, o valor do atributo `value` do `` será um array dos valores `value` dos `` atualmente selecionados. Nota: No modo de seleção múltipla, o valor do atributo `value` do `` é um array e só pode ser lido e definido por propriedades JavaScript. ```html

Day

Week

Month

Day

Week

Month

``` ### Ícone {#example-icon} No elemento ``, use 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

Day

Week

Month

``` No elemento ``, adicione o atributo `selected-icon` para definir o ícone do Material Icons no estado selecionado. Você também pode usar o slot `selected-icon`. ```html

Day

Week

``` ### Link {#example-link} No elemento ``, 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

Link

Week

Month

``` ### Estado desabilitado e carregando {#example-disabled} Use o atributo `disabled` no elemento `` para desabilitar todo o grupo de botões segmentados. ```html

Day

Week

Month

``` No elemento ``, adicione o atributo `disabled` para desabilitar um botão específico; adicione o atributo `loading` para adicionar um estado de carregamento a um botão específico. ```html

Day

Week

Month

Year

``` ## mdui-segmented-button-group API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
full-width	fullWidth	true	boolean	false	Define se deve preencher a largura do elemento pai.
selects	selects	true	'single' \| 'multiple'		Estado de seleção dos botões segmentados. O padrão é não selecionável. Os valores possíveis são: `single`: Seleção única. `multiple`: Seleção múltipla.
disabled	disabled	true	boolean	false	Define se o componente está desabilitado.
required	required	true	boolean	false	Define se, ao enviar o formulário, é obrigatório que algum botão esteja selecionado.
form	form	true	string		O elemento `<form>` associado. O valor deste atributo deve ser o `id` de um elemento `<form>` na mesma página. Se este atributo não for especificado, o elemento precisa ser um elemento filho de um `<form>`. Com este atributo, você pode colocar o elemento em qualquer lugar da página, não apenas como filho do elemento `<form>`.
name	name	true	string	''	O nome usado ao enviar o formulário, que será enviado com os dados do formulário.
value	value	false	string \| string[]	''	O valor do `<mdui-segmented-button>` atualmente selecionado. Nota: O atributo HTML desta propriedade é sempre uma string e só pode definir o valor inicial via atributo HTML quando `selects="single"`. O valor da propriedade JavaScript é uma string quando `selects="single"`, e um array de strings quando `selects="multiple"`. Portanto, quando `selects="multiple"`, para modificar este valor, só é possível alterando a propriedade JavaScript.
undefined	defaultValue	false	string \| string[]	''	O valor selecionado por padrão. Ao redefinir o formulário, será restaurado para este valor padrão. Esta propriedade só pode ser definida via propriedade JavaScript.
undefined	validity	false	ValidityState		Objeto que representa o estado de validação do formulário. Consulte `ValidityState` para mais detalhes.
undefined	validationMessage	false	string		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.

### Métodos

Nome Descrição

checkValidity(): boolean

Verifica se o campo do formulário passou na validação. Se não passou, retorna false e dispara o evento invalid; se passou, retorna true.

reportValidity(): boolean

Verifica se o campo do formulário passou na validação. Se não passou, retorna false e dispara o evento invalid; se passou, retorna true.

Se a validação falhar, também exibe uma mensagem de erro no componente.

setCustomValidity(message: string): void

Define um texto de erro personalizado. Enquanto este texto não estiver vazio, indica que o campo não passou na validação.

### Eventos

Nome	Descrição
change	Disparado quando o valor selecionado muda.
invalid	Disparado quando a validação do campo do formulário falha.

### Slots

Nome	Descrição
(padrão)	Componentes `<mdui-segmented-button>`.

### Propriedades CSS personalizadas

Nome	Descrição
--shape-corner	Tamanho da borda arredondada do componente. Pode ser um valor em pixels, mas é recomendado usar os design tokens.

## mdui-segmented-button API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
icon	icon	true	string		Nome do ícone Material Icons à esquerda. Também pode ser definido via `slot="icon"`.
end-icon	endIcon	true	string		Nome do ícone Material Icons à direita. Também pode ser definido via `slot="end-icon"`.
selected-icon	selectedIcon	true	string		Nome do ícone Material Icons para o estado selecionado. Também pode ser definido via `slot="selected-icon"`.
href	href	true	string		A URL de destino do link. Ao definir esta propriedade, o componente será renderizado internamente como um elemento `<a>` e poderá usar atributos de link.
download	download	true	string		O nome do arquivo para download. Nota: Esta propriedade só é válida quando o atributo `href` está definido.
target	target	true	'_blank' \| '_parent' \| '_self' \| '_top'		Define como o link será aberto. Os valores possíveis são: `_blank`: Abre o link em uma nova janela `_parent`: Abre o link no frame pai `_self`: Padrão. Abre o link no frame atual `_top`: Abre o link na janela inteira Nota: Esta propriedade só é válida quando o atributo `href` está definido.
rel	rel	true	'alternate' \| 'author' \| 'bookmark' \| 'external' \| 'help' \| 'license' \| 'me' \| 'next' \| 'nofollow' \| 'noreferrer' \| 'opener' \| 'prev' \| 'search' \| 'tag'		A relação entre o documento atual e o documento vinculado. Os valores possíveis são: `alternate`: Versão alternativa do documento atual `author`: Autor do documento atual ou artigo `bookmark`: Link permanente para a seção ancestral mais próxima `external`: O documento referenciado não está no mesmo site do documento atual `help`: Link para documentação de ajuda relacionada `license`: O conteúdo principal do documento atual está coberto pela licença de direitos autorais do arquivo referenciado `me`: O documento atual representa o proprietário do conteúdo vinculado `next`: O documento atual faz parte de uma série, e o documento referenciado é o próximo da série `nofollow`: O autor ou editor do documento atual não endossa o arquivo referenciado `noreferrer`: Não inclui o cabeçalho `Referer`. Tem efeito semelhante ao `noopener` `opener`: Se o hiperlink criar um contexto de navegação de nível superior (ou seja, o valor do atributo `target` for `_blank`), cria um contexto de navegação auxiliar `prev`: O documento atual faz parte de uma série, e o documento referenciado é o anterior da série `search`: Fornece um link para um recurso que pode ser usado para pesquisar o arquivo atual e suas páginas relacionadas `tag`: Fornece uma tag (identificada pelo endereço fornecido) aplicável ao documento atual Nota: Disponível apenas quando o atributo `href` é especificado.
autofocus	autofocus	true	boolean	false	Define se o elemento deve receber foco automaticamente após o carregamento da página.
tabindex	tabIndex	false	number		A ordem do elemento ao navegar com a tecla Tab.
disabled	disabled	true	boolean	false	Define se o componente está desabilitado.
loading	loading	true	boolean	false	Define se o componente está em estado de carregamento.
name	name	true	string	''	O nome do botão, que será enviado com os dados do formulário. Nota: Esta propriedade só é válida quando o atributo `href` não está definido.
value	value	true	string	''	O valor inicial do botão, que será enviado com os dados do formulário. Nota: Esta propriedade só é válida quando o atributo `href` não está definido.
type	type	true	'submit' \| 'reset' \| 'button'	'button'	O tipo do botão. O tipo padrão é `button`. Os tipos possíveis são: `submit`: Clicar no botão envia os dados do formulário para o servidor `reset`: Clicar no botão redefine todos os campos do formulário para seus valores iniciais `button`: Este tipo de botão não tem comportamento padrão Nota: Esta propriedade só é válida quando o atributo `href` não é especificado.
form	form	true	string		O elemento `<form>` associado. O valor deste atributo deve ser o `id` de um elemento `<form>` na mesma página. Se este atributo não for especificado, o elemento precisa ser um elemento filho de um `<form>`. Com este atributo, você pode colocar o elemento em qualquer lugar da página, não apenas como filho do elemento `<form>`. Nota: Esta propriedade só é válida quando o atributo `href` não é especificado.
formaction	formAction	true	string		Especifica a URL para envio do formulário. Se este atributo for especificado, ele substituirá o atributo `action` do elemento `<form>`. Nota: Esta propriedade só é válida quando o atributo `href` não é especificado e `type="submit"`.
formenctype	formEnctype	true	'application/x-www-form-urlencoded' \| 'multipart/form-data' \| 'text/plain'		Especifica o tipo de conteúdo ao enviar o formulário para o servidor. Os valores possíveis são: `application/x-www-form-urlencoded`: Valor padrão quando o atributo não é especificado `multipart/form-data`: Usado quando o formulário contém um elemento `<input type="file">` `text/plain`: Novo no HTML5, usado para depuração Se este atributo for especificado, ele substituirá o atributo `enctype` do elemento `<form>`. Nota: Esta propriedade só é válida quando o atributo `href` não é especificado e `type="submit"`.
formmethod	formMethod	true	'post' \| 'get'		Especifica o método HTTP a ser usado ao enviar o formulário. Os valores possíveis são: `post`: Os dados do formulário são incluídos no corpo do formulário e enviados ao servidor `get`: Os dados do formulário são anexados à URI do formulário com `?` 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 Se este atributo for definido, ele substituirá o atributo `method` do elemento `<form>`. Nota: Esta propriedade só é válida quando o atributo `href` não é definido e `type="submit"`.
formnovalidate	formNoValidate	true	boolean	false	Se este atributo for definido, a validação do formulário não será executada ao enviar. Se este atributo for definido, ele substituirá o atributo `novalidate` do elemento `<form>`. Nota: Esta propriedade só é válida quando o atributo `href` não é definido e `type="submit"`.
formtarget	formTarget	true	'_self' \| '_blank' \| '_parent' \| '_top'		Onde exibir a resposta recebida após o envio do formulário. Os valores possíveis são: `_self`: Opção padrão, abre no frame atual `_blank`: Abre em uma nova janela `_parent`: Abre no frame pai `_top`: Abre na janela inteira Se este atributo for definido, ele substituirá o atributo `target` do elemento `<form>`. Nota: Esta propriedade só é válida quando o atributo `href` não é definido e `type="submit"`.
undefined	validity	false	ValidityState		Objeto que representa o estado de validação do formulário. Consulte `ValidityState` para mais detalhes.
undefined	validationMessage	false	string		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.

### Métodos

Nome	Descrição
click(): void	Simula um clique do mouse no elemento.
focus(options?: FocusOptions): void	Define o foco no elemento atual. Você pode passar um objeto como argumento, com as seguintes propriedades: `preventScroll`: 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 `true`.
blur(): void	Remove o foco do elemento atual.
checkValidity(): boolean	Verifica se o campo do formulário passou na validação. Se não passou, retorna `false` e dispara o evento `invalid`; se passou, retorna `true`.
reportValidity(): boolean	Verifica se o campo do formulário passou na validação. Se não passou, retorna `false` e dispara o evento `invalid`; se passou, retorna `true`. Se a validação falhar, também exibe uma mensagem de erro no componente.
setCustomValidity(message: string): void	Define um texto de erro personalizado. Enquanto este texto não estiver vazio, indica que o campo não passou na validação.

### Eventos

Nome	Descrição
focus	Disparado ao receber foco.
blur	Disparado ao perder o foco.
invalid	Disparado quando a validação do campo do formulário falha.

### Slots

Nome	Descrição
(padrão)	Conteúdo de texto do item de botão segmentado.
icon	Ícone à esquerda do item de botão segmentado.
selected-icon	Ícone à esquerda no estado selecionado.
end-icon	Ícone à direita do item de botão segmentado.

### CSS Parts

Nome	Descrição
button	Elemento `<button>` ou `<a>` interno.
icon	Ícone à esquerda.
selected-icon	Ícone à esquerda no estado selecionado.
end-icon	Ícone à direita.
label	Conteúdo de texto.
loading	Elemento `<mdui-circular-progress>` no estado de carregamento.

# Componente Slider O slider permite que os usuários selecionem um valor em uma escala deslizando o botão. ## Como usar {#usage} Importe o componente conforme necessário: ```js import 'mdui/components/slider.js'; ``` Importe o tipo TypeScript do componente conforme necessário: ```ts import type { Slider } from 'mdui/components/slider.js'; ``` Exemplo de uso: ```html ``` ## Exemplos {#examples} ### Valor padrão {#example-value} Através do atributo `value`, você pode ler ou definir o valor atual do slider. ```html ``` ### Estado desabilitado {#example-disabled} Use o atributo `disabled` para desabilitar o slider. ```html ``` ### Intervalo {#example-min-max} Use os atributos `min` e `max` para definir o valor mínimo e máximo do slider. ```html ``` ### Incremento {#example-step} Use o atributo `step` para definir o incremento do slider. ```html ``` ### Marcas de graduação {#example-tickmarks} Use o atributo `tickmarks` para exibir marcas de graduação no slider. ```html ``` ### Ocultar dica de texto {#example-nolabel} Use o atributo `nolabel` para ocultar a dica de texto no slider. ```html ``` ### Modificar a dica de texto {#example-labelFormatter} Através da propriedade JavaScript `labelFormatter`, você pode modificar o formato da dica de texto. Esta propriedade é uma função que recebe o valor atual do slider como parâmetro e retorna o texto que você deseja exibir. ```html ``` ## mdui-slider API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
value	value	false	number	0	O valor do slider, que será enviado com os dados do formulário.
undefined	defaultValue	false	number	0	Valor padrão. Ao redefinir o formulário, será restaurado para este valor padrão. Esta propriedade só pode ser definida via propriedade JavaScript.
autofocus	autofocus	true	boolean	false	Define se o elemento deve receber foco automaticamente após o carregamento da página.
tabindex	tabIndex	false	number		A ordem do elemento ao navegar com a tecla Tab.
min	min	true	number	0	O valor mínimo do slider. O padrão é `0`.
max	max	true	number	100	O valor máximo do slider. O padrão é `100`.
step	step	true	number	1	O intervalo de incremento. O padrão é `1`.
tickmarks	tickmarks	true	boolean	false	Define se devem ser adicionadas marcas de escala.
nolabel	nolabel	true	boolean	false	Define se o texto do rótulo deve ser ocultado.
disabled	disabled	true	boolean	false	Define se o componente está desabilitado.
form	form	true	string		O elemento `<form>` associado. O valor deste atributo deve ser o `id` de um elemento `<form>` na mesma página. Se este atributo não for especificado, o elemento precisa ser um elemento filho de um `<form>`. Com este atributo, você pode colocar o elemento em qualquer lugar da página, não apenas como filho do elemento `<form>`.
name	name	true	string	''	O nome do slider, que será enviado com os dados do formulário.
undefined	validity	false	ValidityState		Objeto que representa o estado de validação do formulário. Consulte `ValidityState` para mais detalhes.
undefined	validationMessage	false	string		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.
undefined	labelFormatter	false	(value: number) => string		Função usada para personalizar o formato de exibição do rótulo. O parâmetro da função é o valor atual do slider, e o valor de retorno é o texto que se deseja exibir.

### Métodos

Nome	Descrição
click(): void	Simula um clique do mouse no elemento.
focus(options?: FocusOptions): void	Define o foco no elemento atual. Você pode passar um objeto como argumento, com as seguintes propriedades: `preventScroll`: 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 `true`.
blur(): void	Remove o foco do elemento atual.
checkValidity(): boolean	Verifica se o campo do formulário passou na validação. Se não passou, retorna `false` e dispara o evento `invalid`; se passou, retorna `true`.
reportValidity(): boolean	Verifica se o campo do formulário passou na validação. Se não passou, retorna `false` e dispara o evento `invalid`; se passou, retorna `true`. Se a validação falhar, também exibe uma mensagem de erro no componente.
setCustomValidity(message: string): void	Define um texto de erro personalizado. Enquanto este texto não estiver vazio, indica que o campo não passou na validação.

### Eventos

Nome	Descrição
focus	Disparado ao receber foco.
blur	Disparado ao perder o foco.
change	Disparado quando o valor muda e o elemento perde o foco.
input	Disparado quando o valor muda.
invalid	Disparado quando a validação do campo do formulário falha.

### CSS Parts

Nome	Descrição
track-inactive	Trilha do estado inativo.
track-active	Trilha do estado ativo.
handle	Alça de controle.
label	Texto do rótulo.
tickmark	Marca de escala.

# Componente Snackbar O componente Snackbar é usado para exibir informações breves sobre o processo do aplicativo na página. Além de usar o componente diretamente, mdui também fornece uma função [`mdui.snackbar`](/pt-br/docs/2/functions/snackbar) para simplificar o uso do componente Snackbar. ## Como usar {#usage} Importe o componente conforme necessário: ```js import 'mdui/components/snackbar.js'; ``` Importe o tipo TypeScript do componente conforme necessário: ```ts import type { Snackbar } from 'mdui/components/snackbar.js'; ``` Exemplo de uso: ```html Photo archived

Abrir Snackbar

``` ## Exemplos {#examples} ### Posição {#example-placement} Use o atributo `placement` para definir a posição de exibição do Snackbar. ```html

Photo archived

top-start

Photo archived

top

Photo archived

top-end

Photo archived

bottom-start

Photo archived

bottom

Photo archived

bottom-end

``` ### Botão de ação {#example-action} Use o atributo `action` para adicionar um botão de ação no lado direito do Snackbar, especificando o texto do botão. Clicar no botão de ação dispara o evento `action-click`. Se você quiser que o botão de ação apareça no estado de carregamento, adicione o atributo `action-loading`. ```html Photo archived

Abrir Snackbar

``` Você também pode adicionar um elemento personalizado no lado direito do Snackbar pelo slot `action`. ```html Photo archived Undo

Abrir Snackbar

``` ### Com fechamento {#example-closeable} Use o atributo `closeable` para que um botão de fechar apareça no lado direito do Snackbar. Clicar neste botão fecha o Snackbar e dispara o evento `close`. ```html Photo archived

Abrir Snackbar

``` Você pode personalizar o elemento do botão de fechar pelo slot `close-button`. ```html Photo archived

Abrir Snackbar

``` Defina o atributo `close-icon` para modificar o ícone do Material Icons no botão de fechar padrão. Você também pode personalizar o elemento do ícone no botão de fechar pelo slot `close-icon`. ```html Photo archived

Abrir Snackbar

``` ### Número de linhas do texto {#example-message-line} Por padrão, o texto da mensagem não tem limite de linhas. Você pode usar o atributo `message-line` para limitar o número de linhas do texto, no máximo 2 linhas. ```html The item already has the label "travel". You can add a new label. You can add a new label.

Abrir Snackbar

``` ### Atraso para fechamento automático {#example-auto-close-delay} Use o atributo `auto-close-delay` para definir o atraso para o fechamento automático, em milissegundos. O valor padrão é 5000 milissegundos. ```html Photo archived

Abrir Snackbar

``` ### Fechar ao clicar fora da área {#example-close-on-outside-click} Use o atributo `close-on-outside-click` para fechar o Snackbar ao clicar fora da área do Snackbar. ```html Photo archived

Abrir Snackbar

``` ## mdui-snackbar API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
open	open	true	boolean	false	Define se o Snackbar está visível.
placement	placement	true	'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end'	'bottom'	Posição de exibição do Snackbar. O padrão é `bottom`. Os valores possíveis são: `top`: Topo centralizado. `top-start`: Topo alinhado à esquerda. `top-end`: Topo alinhado à direita. `bottom`: Base centralizada. `bottom-start`: Base alinhada à esquerda. `bottom-end`: Base alinhada à direita.
action	action	true	string		Texto do botão de ação. Também pode ser definido via `slot="action"` para configurar o botão de ação.
action-loading	actionLoading	true	boolean	false	Define se o botão de ação está em estado de carregamento.
closeable	closeable	true	boolean	false	Define se deve ser exibido um botão de fechar à direita.
close-icon	closeIcon	true	string		Nome do ícone Material Icons para o botão de fechar. Também pode ser definido via `slot="close-icon"`.
message-line	messageLine	true	1 \| 2		Número máximo de linhas exibidas para o texto da mensagem. O padrão é sem limite. Os valores possíveis são: `1`: No máximo uma linha. `2`: No máximo duas linhas.
auto-close-delay	autoCloseDelay	true	number	5000	Atraso, em milissegundos, para fechar automaticamente. Defina como `0` para não fechar automaticamente. O padrão é 5000 milissegundos.
close-on-outside-click	closeOnOutsideClick	true	boolean	false	Define se clicar ou tocar fora da área do Snackbar deve fechá-lo.

### Eventos

Nome	Descrição
open	Disparado quando o Snackbar começa a ser exibido. Pode impedir a exibição chamando `event.preventDefault()`.
opened	Disparado quando a animação de exibição do Snackbar é concluída.
close	Disparado quando o Snackbar começa a ser ocultado. Pode impedir o fechamento chamando `event.preventDefault()`.
closed	Disparado quando a animação de ocultação do Snackbar é concluída.
action-click	Disparado ao clicar no botão de ação.

### Slots

Nome	Descrição
(padrão)	Conteúdo de texto da mensagem do Snackbar.
action	Botão de ação à direita.
close-button	Botão de fechar à direita. É necessário que o atributo `closeable` esteja definido como `true` para ser exibido.
close-icon	Ícone dentro do botão de fechar.

### CSS Parts

Nome	Descrição
message	Texto da mensagem.
action	Botão de ação.
close-button	Botão de fechar.
close-icon	Ícone dentro do botão de fechar.

### Propriedades CSS personalizadas

Nome	Descrição
--shape-corner	Tamanho da borda arredondada do componente. Pode ser um valor em pixels, mas é recomendado usar os design tokens.
--z-index	Valor CSS `z-index` do componente.

# Componente Switch O componente switch é usado para alternar o estado ligado/desligado de uma única opção, com um design de interação intuitivo que permite aos usuários ajustar as configurações facilmente. ## Como usar {#usage} Importe o componente conforme necessário: ```js import 'mdui/components/switch.js'; ``` Importe o tipo TypeScript do componente conforme necessário: ```ts import type { Switch } from 'mdui/components/switch.js'; ``` Exemplo de uso: ```html ``` ## Exemplos {#examples} ### Estado selecionado {#example-checked} Quando o switch está selecionado, o valor do atributo `checked` é `true`. Você também pode adicionar o atributo `checked` para que o switch inicie selecionado por padrão. ```html ``` ### Estado desabilitado {#example-disabled} Use o atributo `disabled` para desabilitar o componente switch. ```html ``` ### Ícone {#example-icon} Você pode usar o atributo `unchecked-icon` para definir o ícone do Material Icons no estado não selecionado e o atributo `checked-icon` para definir o ícone no estado selecionado. Você também pode usar os slots `unchecked-icon` e `checked-icon` para personalizar os elementos de ícone dos estados não selecionado e selecionado. ```html

``` ## mdui-switch API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
disabled	disabled	true	boolean	false	Define se o componente está desabilitado.
checked	checked	true	boolean	false	Define se o componente está selecionado.
undefined	defaultChecked	false	boolean	false	Estado de seleção padrão. Ao redefinir o formulário, será restaurado para este estado. Esta propriedade só pode ser definida via propriedade JavaScript.
unchecked-icon	uncheckedIcon	true	string		Nome do ícone Material Icons para o estado não selecionado. Também pode ser definido via `slot="unchecked-icon"`.
checked-icon	checkedIcon	true	string		Nome do ícone Material Icons para o estado selecionado. Também pode ser definido via `slot="checked-icon"`. O padrão é o ícone `check`. Pode-se passar uma string vazia para remover o ícone padrão.
required	required	true	boolean	false	Define se, ao enviar o formulário, é obrigatório que este switch esteja selecionado.
form	form	true	string		O elemento `<form>` associado. O valor deste atributo deve ser o `id` de um elemento `<form>` na mesma página. Se este atributo não for especificado, o elemento precisa ser um elemento filho de um `<form>`. Com este atributo, você pode colocar o elemento em qualquer lugar da página, não apenas como filho do elemento `<form>`.
name	name	true	string	''	O nome do switch, que será enviado com os dados do formulário.
value	value	true	string	'on'	O valor do switch, que será enviado com os dados do formulário.
undefined	validity	false	ValidityState		Objeto que representa o estado de validação do formulário. Consulte `ValidityState` para mais detalhes.
undefined	validationMessage	false	string		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.
autofocus	autofocus	true	boolean	false	Define se o elemento deve receber foco automaticamente após o carregamento da página.
tabindex	tabIndex	false	number		A ordem do elemento ao navegar com a tecla Tab.

### Métodos

Nome	Descrição
checkValidity(): boolean	Verifica se o campo do formulário passou na validação. Se não passou, retorna `false` e dispara o evento `invalid`; se passou, retorna `true`.
reportValidity(): boolean	Verifica se o campo do formulário passou na validação. Se não passou, retorna `false` e dispara o evento `invalid`; se passou, retorna `true`. Se a validação falhar, também exibe uma mensagem de erro no componente.
setCustomValidity(message: string): void	Define um texto de erro personalizado. Enquanto este texto não estiver vazio, indica que o campo não passou na validação.
click(): void	Simula um clique do mouse no elemento.
focus(options?: FocusOptions): void	Define o foco no elemento atual. Você pode passar um objeto como argumento, com as seguintes propriedades: `preventScroll`: 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 `true`.
blur(): void	Remove o foco do elemento atual.

### Eventos

Nome	Descrição
focus	Disparado ao receber foco.
blur	Disparado ao perder o foco.
change	Disparado quando o estado de seleção muda.
input	Disparado quando o estado de seleção muda.
invalid	Disparado quando a validação do campo do formulário falha.

### Slots

Nome	Descrição
unchecked-icon	Elemento no estado não selecionado.
checked-icon	Elemento no estado selecionado.

### CSS Parts

Nome	Descrição
track	Trilha.
thumb	Contêiner do ícone.
unchecked-icon	Ícone no estado não selecionado.
checked-icon	Ícone no estado selecionado.

### Propriedades CSS personalizadas

Nome	Descrição
--shape-corner	Tamanho da borda arredondada da trilha do componente. Pode ser um valor em pixels, mas é recomendado usar os design tokens.
--shape-corner-thumb	Tamanho da borda arredondada do contêiner do ícone do componente. Pode ser um valor em pixels, mas é recomendado usar os design tokens.

# Componente Tabs O componente tabs é usado para agrupar e exibir conjuntos de dados ou conteúdo, permitindo que os usuários alternem rapidamente entre diferentes categorias. ## Como usar {#usage} Importe os componentes conforme necessário: ```js import 'mdui/components/tabs.js'; import 'mdui/components/tab.js'; import 'mdui/components/tab-panel.js'; ``` Importe os tipos TypeScript dos componentes conforme necessário: ```ts import type { Tabs } from 'mdui/components/tabs.js'; import type { Tab } from 'mdui/components/tab.js'; import type { TabPanel } from 'mdui/components/tab-panel.js'; ``` Exemplo de uso: ```html

Tab 1

Tab 2

Tab 3

Panel 1

Panel 2

Panel 3

``` ## Exemplos {#examples} ### Estilo das abas {#example-variant} Use o atributo `variant` no componente `` para definir o estilo das abas. ```html

Tab 1

Tab 2

Tab 3

Panel 1

Panel 2

Panel 3

Tab 1

Tab 2

Tab 3

Panel 1

Panel 2

Panel 3

``` ### Posição das abas {#example-placement} Use o atributo `placement` no componente `` para definir a posição das abas. ```html

top-start

top

top-end

bottom-start

bottom

bottom-end

left-start

left

left-end

right-start

right

right-end

Tab 1

Tab 2

Tab 3

Panel 1

Panel 2

Panel 3

``` ### Largura total {#example-full-width} Use o atributo `full-width` ao componente `` para fazer as abas ocuparem toda a largura, distribuindo a largura igualmente entre as abas. ```html

Tab 1

Tab 2

Tab 3

Panel 1

Panel 2

Panel 3

``` ### Ícone {#example-icon} Defina o atributo `icon` no componente `` para adicionar um ícone do Material Icons na aba. Você também pode adicionar um elemento de ícone pelo slot `icon`. Use o atributo `inline` para alinhar o ícone e o texto horizontalmente. ```html

Tab 1

Tab 2

Tab 3

Panel 1

Panel 2

Panel 3

``` ### Badge {#example-badge} No componente ``, você pode adicionar um badge pelo slot `badge`. ```html

Tab 1 99+

Tab 2

Tab 3

Panel 1

Panel 2

Panel 3

``` ### Conteúdo personalizado {#example-custom} Use o slot `custom` no componente `` para personalizar completamente o conteúdo da aba. ```html

Tab 1 Icon

Tab 2

Tab 3

Panel 1

Panel 2

Panel 3

``` ## mdui-tab-panel API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
value	value	true	string		O valor do item de painel da aba.

### Slots

Nome	Descrição
(padrão)	Conteúdo do item de painel da aba.

## mdui-tab API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
value	value	true	string		O valor do item de navegação por abas.
icon	icon	true	string		Nome do ícone Material Icons. Também pode ser definido via `slot="icon"`.
inline	inline	true	boolean	false	Define se o ícone e o texto devem ser alinhados horizontalmente.
autofocus	autofocus	true	boolean	false	Define se o elemento deve receber foco automaticamente após o carregamento da página.
tabindex	tabIndex	false	number		A ordem do elemento ao navegar com a tecla Tab.

### Métodos

Nome Descrição

click(): void

Simula um clique do mouse no elemento.

focus(options?: FocusOptions): void

Define o foco no elemento atual.

Você pode passar um objeto como argumento, com as seguintes propriedades:

preventScroll: 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 true.

blur(): void

Remove o foco do elemento atual.

### Eventos

Nome	Descrição
focus	Disparado ao receber foco.
blur	Disparado ao perder o foco.

### Slots

Nome	Descrição
(padrão)	Conteúdo de texto do item de navegação por abas.
icon	Ícone no item de navegação por abas.
badge	Badge.
custom	Personaliza todo o conteúdo dentro do item de navegação por abas.

### CSS Parts

Nome	Descrição
container	Contêiner do item de navegação por abas.
icon	Ícone no item de navegação por abas.
label	Texto do item de navegação por abas.

## mdui-tabs API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
variant	variant	true	'primary' \| 'secondary'	'primary'	Forma das abas. Os valores possíveis são: `primary`: Adequado para cenários onde as abas estão localizadas abaixo do `<mdui-top-app-bar>` para alternar entre as páginas principais do aplicativo. `secondary`: Adequado para cenários onde as abas estão localizadas em uma página para alternar entre um conjunto de conteúdos relacionados.
value	value	true	string		O valor do `<mdui-tab>` atualmente ativo.
placement	placement	true	'top-start' \| 'top' \| 'top-end' \| 'bottom-start' \| 'bottom' \| 'bottom-end' \| 'left-start' \| 'left' \| 'left-end' \| 'right-start' \| 'right' \| 'right-end'	'top-start'	Posição das abas. O padrão é `top-start`. Os valores possíveis são: `top-start`: Acima, alinhado à esquerda. `top`: Acima, centralizado. `top-end`: Acima, alinhado à direita. `bottom-start`: Abaixo, alinhado à esquerda. `bottom`: Abaixo, centralizado. `bottom-end`: Abaixo, alinhado à direita. `left-start`: À esquerda, alinhado ao topo. `left`: À esquerda, centralizado. `left-end`: À esquerda, alinhado à base. `right-start`: À direita, alinhado ao topo. `right`: À direita, centralizado. `right-end`: À direita, alinhado à base.
full-width	fullWidth	true	boolean	false	Define se deve preencher a largura do elemento pai.

### Eventos

Nome	Descrição
change	Disparado quando o valor selecionado muda.

### Slots

Nome	Descrição
(padrão)	Elementos `<mdui-tab>`.
panel	Elementos `<mdui-tab-panel>`.

### CSS Parts

Nome	Descrição
container	Contêiner dos elementos `<mdui-tab>`.
indicator	Indicador de estado ativo.

# Componente TextField O campo de texto permite que os usuários insiram texto na página, geralmente usado em formulários e diálogos. ## Como usar {#usage} Importe o componente conforme necessário: ```js import 'mdui/components/text-field.js'; ``` Importe o tipo TypeScript do componente conforme necessário: ```ts import type { TextField } from 'mdui/components/text-field.js'; ``` Exemplo de uso: ```html ``` ## Exemplos {#examples} ### Forma {#example-variant} Use o atributo `variant` para definir a forma do campo de texto. ```html

``` ### Texto auxiliar {#example-helper-text} Use o atributo `label` para definir o texto do rótulo acima do campo de texto. ```html ``` Use o atributo `placeholder` para definir o texto de espaço reservado quando não há valor. ```html ``` Use o atributo `helper` para definir o texto de ajuda na parte inferior do campo de texto. Você também pode usar o slot `helper` para definir o texto de ajuda. Adicione `helper-on-focus` para exibir o texto de ajuda apenas quando o campo de texto está em foco. ```html

Supporting text

``` ### Com limpeza {#example-clearable} Use o atributo `clearable` para que, quando o campo de texto tiver um valor, um botão de limpeza apareça no lado direito. ```html ``` ### Texto alinhado à direita {#example-end-aligned} Use o atributo `end-aligned` para alinhar o texto à direita. ```html ``` ### Texto e ícones antes/depois {#example-prefix-suffix} Defina os atributos `icon` e `end-icon` para adicionar ícones do Material Icons à esquerda e à direita do campo de texto. Você também pode adicionar elementos pelos slots `icon` e `end-icon`. ```html

``` Defina os atributos `prefix` e `suffix` para adicionar texto à esquerda e à direita do campo de texto. Esses textos só são exibidos quando o campo de texto está em foco ou tem um valor. Você também pode usar os slots `prefix` e `suffix` para adicionar elementos de texto. ```html

$ /100 ``` ### Modo somente leitura {#example-readonly} Use o atributo `readonly` para colocar o campo de texto no modo somente leitura. ```html ``` ### Modo desabilitado {#example-disabled} Use o atributo `disabled` para desabilitar o campo de texto. ```html ``` ### Campo de texto multilinha {#example-rows} Use o atributo `rows` para definir o número de linhas do campo de texto multilinha. ```html ``` Use o atributo `autosize` para fazer o campo de texto ajustar automaticamente a altura conforme o comprimento do conteúdo. Use os atributos `min-rows` e `max-rows` para especificar o número mínimo e máximo de linhas ao ajustar automaticamente a altura. ```html

``` ### Contador de caracteres {#example-counter} Quando o número máximo de caracteres é definido pelo atributo `maxlength`, você pode adicionar o atributo `counter` para exibir o contador de caracteres abaixo do campo de texto. ```html ``` ### Campo de senha {#example-password} Quando `type="password"`, adicione o atributo `toggle-password` para adicionar um botão de alternância de visibilidade da senha no lado direito do campo de texto. ```html ``` ## mdui-text-field API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
variant	variant	true	'filled' \| 'outlined'	'filled'	Forma do campo de texto. O padrão é `filled`. Os valores possíveis são: `filled`: Campo de texto com cor de fundo; efeito visual mais forte. `outlined`: Campo de texto com borda; efeito visual mais suave.
type	type	true	'text' \| 'number' \| 'password' \| 'url' \| 'email' \| 'search' \| 'tel' \| 'hidden' \| 'date' \| 'datetime-local' \| 'month' \| 'time' \| 'week'	'text'	Tipo de entrada do campo de texto. O padrão é `text`. Os valores possíveis são: `text`: Valor padrão. Campo de texto. `number`: Permite apenas entrada de números. Em dispositivos com teclado dinâmico, exibe teclado numérico. `password`: Usado para entrada de senha; o valor é ocultado. `url`: Usado para entrada de URL; valida o formato da URL. Em dispositivos com teclado dinâmico, exibe teclado apropriado. `email`: Usado para entrada de e-mail; valida o formato do e-mail. Em dispositivos com teclado dinâmico, exibe teclado apropriado. `search`: Usado para caixa de pesquisa. Em dispositivos com teclado dinâmico, o ícone Enter se torna ícone de pesquisa. `tel`: Usado para entrada de número de telefone. Em dispositivos com teclado dinâmico, exibe teclado numérico de telefone. `hidden`: Oculta o controle, mas seu valor ainda é enviado ao servidor. `date`: Controle para entrada de data (ano, mês, dia, sem hora). Em navegadores suportados, abre um seletor de data ou um seletor de rolagem numérica. `datetime-local`: Controle para entrada de data e hora, sem fuso horário. Em navegadores suportados, abre um seletor de data ou um seletor de rolagem numérica. `month`: Controle para entrada de mês e ano, sem fuso horário. `time`: Controle para entrada de hora, sem fuso horário. `week`: Controle para entrada de data composta por ano e número da semana, sem fuso horário.
name	name	true	string	''	O nome do campo de texto, que será enviado com os dados do formulário.
value	value	false	string	''	O valor do campo de texto, que será enviado com os dados do formulário.
undefined	defaultValue	false	string	''	Valor padrão. Ao redefinir o formulário, será restaurado para este valor padrão. Esta propriedade só pode ser definida via propriedade JavaScript.
label	label	true	string		Texto do rótulo.
placeholder	placeholder	true	string		Texto de placeholder.
helper	helper	true	string		Texto de ajuda na parte inferior do campo de texto. Também pode ser definido via `slot="helper"`.
helper-on-focus	helperOnFocus	true	boolean	false	Define se o texto de ajuda na parte inferior deve ser exibido apenas quando o campo recebe foco.
clearable	clearable	true	boolean	false	Define se o conteúdo do campo de texto pode ser limpo.
clear-icon	clearIcon	true	string		Nome do ícone Material Icons para o botão de limpar, exibido à direita do campo de texto quando ele é limpável. Também pode ser definido via `slot="clear-icon"`.
end-aligned	endAligned	true	boolean	false	Define se o texto deve ser alinhado à direita.
prefix	prefix	true	string		Texto de prefixo do campo de texto. Exibido apenas quando o campo está focado ou tem valor. Também pode ser definido via `slot="prefix"`.
suffix	suffix	true	string		Texto de sufixo do campo de texto. Exibido apenas quando o campo está focado ou tem valor. Também pode ser definido via `slot="suffix"`.
icon	icon	true	string		Nome do ícone Material Icons para o ícone de prefixo do campo de texto. Também pode ser definido via `slot="icon"`.
end-icon	endIcon	true	string		Nome do ícone Material Icons para o ícone de sufixo do campo de texto. Também pode ser definido via `slot="end-icon"`.
error-icon	errorIcon	true	string		Nome do ícone Material Icons exibido à direita do campo de texto quando a validação do campo do formulário falha. Também pode ser definido via `slot="error-icon"`.
form	form	true	string		O elemento `<form>` associado. O valor deste atributo deve ser o `id` de um elemento `<form>` na mesma página. Se este atributo não for especificado, o elemento precisa ser um elemento filho de um `<form>`. Com este atributo, você pode colocar o elemento em qualquer lugar da página, não apenas como filho do elemento `<form>`.
readonly	readonly	true	boolean	false	Define se o componente está no modo somente leitura.
disabled	disabled	true	boolean	false	Define se a caixa de entrada está desabilitada.
required	required	true	boolean	false	Define se, ao enviar o formulário, é obrigatório que este campo seja preenchido.
rows	rows	true	number		Número fixo de linhas exibidas para o campo de texto.
autosize	autosize	true	boolean	false	Define se a altura do campo de texto deve ser ajustada automaticamente com base no conteúdo digitado.
min-rows	minRows	true	number		Número mínimo de linhas quando `autosize` é `true`.
max-rows	maxRows	true	number		Número máximo de linhas quando `autosize` é `true`.
minlength	minlength	true	number		Número mínimo de caracteres permitido.
maxlength	maxlength	true	number		Número máximo de caracteres permitido.
counter	counter	true	boolean	false	Define se deve exibir a contagem de caracteres. Só é válido quando `maxlength` é especificado.
min	min	true	number		Quando `type` é `number`, o valor mínimo permitido.
max	max	true	number		Quando `type` é `number`, o valor máximo permitido.
step	step	true	number		Quando `type` é `number`, o incremento/decremento ao usar as setas.
pattern	pattern	true	string		Expressão regular usada para validação do formulário.
toggle-password	togglePassword	true	boolean	false	Quando `type` é `password`, definir esta propriedade adiciona um botão para alternar entre texto visível e oculto.
show-password-icon	showPasswordIcon	true	string		Ícone Material Icons para o botão de alternância de senha, exibido quando a senha está visível. Também pode ser definido via `slot="show-password-icon"`.
hide-password-icon	hidePasswordIcon	true	string		Ícone Material Icons para o botão de alternância de senha, exibido quando a senha está oculta. Também pode ser definido via `slot="hide-password-icon"`.
autocapitalize	autocapitalize	true	'none' \| 'sentences' \| 'words' \| 'characters'		Atributo não padrão do iOS, usado para controlar se a primeira letra do texto é automaticamente capitalizada. Válido no iOS 5 e posteriores. Os valores possíveis são: `none`: Desativa a capitalização da primeira letra. `sentences`: Capitaliza a primeira letra de frases. `words`: Capitaliza a primeira letra de palavras. `characters`: Capitaliza todas as letras.
autocorrect	autocorrect	true	string		Atributo `autocorrect` do elemento `<input>`.
autocomplete	autocomplete	true	string		Atributo `autocomplete` do elemento `<input>`.
enterkeyhint	enterkeyhint	true	'enter' \| 'done' \| 'go' \| 'next' \| 'previous' \| 'search' \| 'send'		Atributo `enterkeyhint` do elemento `<input>`, usado para personalizar o texto ou ícone exibido na tecla Enter do teclado virtual. A aparência real depende do dispositivo e idioma do usuário. Os valores possíveis são: `enter`: Insere uma nova linha. `done`: Conclui a entrada; fecha o teclado virtual. `go`: Navega para o destino do texto inserido. `next`: Move para o próximo campo de entrada. `previous`: Move para o campo de entrada anterior. `search`: Navega para os resultados da pesquisa. `send`: Envia a mensagem de texto.
spellcheck	spellcheck	true	boolean	false	Define se a verificação ortográfica está habilitada.
inputmode	inputmode	true	'none' \| 'text' \| 'decimal' \| 'numeric' \| 'tel' \| 'search' \| 'email' \| 'url'		Atributo `inputmode` do elemento `<input>`, usado para personalizar o tipo de teclado virtual. Os valores possíveis são: `none`: Sem teclado virtual. Útil quando se quer implementar seu próprio controle de entrada de teclado. `text`: Teclado padrão para entrada de texto. `decimal`: Teclado para entrada de números decimais, podendo incluir ponto decimal `.` ou vírgula de milhar `,`. `numeric`: Exibe teclado numérico de 0 a 9. `tel`: Teclado numérico de telefone, incluindo dígitos de 0 a 9, asterisco `*` e cerquilha `#`. `search`: Teclado virtual otimizado para entrada de pesquisa; o botão de envio geralmente exibe `search` ou "Pesquisar". `email`: Teclado virtual otimizado para entrada de endereço de e-mail, geralmente com teclas como `@`, `.`. `url`: Teclado virtual otimizado para entrada de URL, geralmente com teclas como `.`, `/`, `#`.
undefined	validity	false	ValidityState		Objeto que representa o estado de validação do formulário. Consulte `ValidityState` para mais detalhes.
undefined	validationMessage	false	string		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.
undefined	valueAsNumber	false	number		Obtém o valor atual e converte para o tipo `number`; ou define um valor do tipo `number`. Se o valor não puder ser convertido para `number`, retorna `NaN`.
autofocus	autofocus	true	boolean	false	Define se o elemento deve receber foco automaticamente após o carregamento da página.
tabindex	tabIndex	false	number		A ordem do elemento ao navegar com a tecla Tab.

### Métodos

Nome	Descrição
select(): void	Seleciona o texto no campo de texto.
setSelectionRange(start: number, end: number, direction: 'forward' \| 'backward' \| 'none'): void	Seleciona um intervalo específico no campo de texto.
setRangeText(replacement: string, start: number, end: number, selectMode: 'select' \| 'start' \| 'end' \| 'preserve'): void	Substitui um intervalo específico do texto no campo de texto por um novo texto.
checkValidity(): boolean	Verifica se o campo do formulário passou na validação. Se não passou, retorna `false` e dispara o evento `invalid`; se passou, retorna `true`.
reportValidity(): boolean	Verifica se o campo do formulário passou na validação. Se não passou, retorna `false` e dispara o evento `invalid`; se passou, retorna `true`. Se a validação falhar, também exibe uma mensagem de erro no componente.
setCustomValidity(message: string): void	Define um texto de erro personalizado. Enquanto este texto não estiver vazio, indica que o campo não passou na validação.
click(): void	Simula um clique do mouse no elemento.
focus(options?: FocusOptions): void	Define o foco no elemento atual. Você pode passar um objeto como argumento, com as seguintes propriedades: `preventScroll`: 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 `true`.
blur(): void	Remove o foco do elemento atual.

### Eventos

Nome	Descrição
focus	Disparado ao receber foco.
blur	Disparado ao perder o foco.
change	Disparado quando o valor do campo de texto muda e o campo perde o foco.
input	Disparado quando o valor do campo de texto muda.
invalid	Disparado quando a validação do campo do formulário falha.
clear	Disparado ao clicar no botão de limpar gerado pelo atributo `clearable`. Pode impedir a limpeza do campo de texto chamando `event.preventDefault()`.

### Slots

Nome	Descrição
icon	Ícone à esquerda.
end-icon	Ícone à direita.
error-icon	Ícone à direita no estado de falha de validação.
prefix	Texto à esquerda.
suffix	Texto à direita.
clear-button	Botão de limpar.
clear-icon	Ícone dentro do botão de limpar.
toggle-password-button	Botão de alternância de visibilidade da senha.
show-password-icon	Ícone dentro do botão de alternância de senha no estado de senha visível.
hide-password-icon	Ícone dentro do botão de alternância de senha no estado de senha oculta.
helper	Texto de ajuda na parte inferior.

### CSS Parts

Nome	Descrição
container	Contêiner do campo de texto.
icon	Ícone à esquerda.
end-icon	Ícone à direita.
error-icon	Ícone à direita no estado de falha de validação.
prefix	Texto à esquerda.
suffix	Texto à direita.
label	Texto do rótulo acima.
input	Elemento `<input>` ou `<textarea>` interno.
clear-button	Botão de limpar.
clear-icon	Ícone dentro do botão de limpar.
toggle-password-button	Botão de alternância de visibilidade da senha.
show-password-icon	Ícone dentro do botão de alternância de senha no estado de senha visível.
hide-password-icon	Ícone dentro do botão de alternância de senha no estado de senha oculta.
supporting	Contêiner de informações auxiliares na parte inferior, incluindo helper, error, counter.
helper	Texto de ajuda na parte inferior.
error	Texto de descrição de erro na parte inferior.
counter	Contador de caracteres no canto inferior direito.

# Componente Tooltip Tooltip é usado para fornecer dicas de texto complementares ou informações contextuais para um elemento específico, ajudando o usuário a entender melhor a função ou propósito do elemento. ## Como usar {#usage} Importe o componente conforme necessário: ```js import 'mdui/components/tooltip.js'; ``` Importe o tipo TypeScript do componente conforme necessário: ```ts import type { Tooltip } from 'mdui/components/tooltip.js'; ``` Exemplo de uso: ```html

button

``` ## Exemplos {#examples} ### Tooltip de texto simples {#example-plain} O padrão é tooltip de texto simples. Use o atributo `content` para definir o conteúdo do tooltip. ```html

button

``` Você também pode definir o conteúdo do tooltip pelo slot `content`. ```html

button

title

content

``` ### Tooltip rico {#example-rich} Defina o atributo `variant` como `rich` para criar um tooltip rico. Use o atributo `headline` para definir o título do tooltip e o atributo `content` para definir o conteúdo do tooltip. ```html

button

``` Você também pode definir o título e o conteúdo do tooltip pelos slots `headline` e `content`. Use o slot `action` para definir os botões de ação do tooltip. ```html

button

Rich tooltip

Rich tooltips bring attention to a particular element of feature that warrants the user's focus. It supports multiple lines of informational text.

Action

``` ### Posição {#example-placement} Use o atributo `placement` para definir a posição do tooltip. ```html

``` ### Modo de acionamento {#example-trigger} Use o atributo `trigger` para definir o modo de acionamento do tooltip. ```html

button

``` ### Atraso para abrir/fechar {#example-delay} Quando o modo de acionamento é `hover`, você pode usar os atributos `open-delay` e `close-delay` para definir o atraso para abrir e fechar o tooltip, em milissegundos. ```html

button

``` ### Estado desabilitado {#example-disabled} Use o atributo `disabled` para desabilitar o tooltip. ```html

button

``` ## mdui-tooltip API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
variant	variant	true	'plain' \| 'rich'	'plain'	Forma do tooltip. O padrão é `plain`. Os valores possíveis são: `plain`: Texto simples, adequado para textos de uma única linha. `rich`: Texto rico, pode conter título, corpo e botões de ação.
placement	placement	true	'auto' \| 'top-left' \| 'top-start' \| 'top' \| 'top-end' \| 'top-right' \| 'bottom-left' \| 'bottom-start' \| 'bottom' \| 'bottom-end' \| 'bottom-right' \| 'left-start' \| 'left' \| 'left-end' \| 'right-start' \| 'right' \| 'right-end'	'auto'	Posição do tooltip. O padrão é `auto`. Os valores possíveis são: `auto`: Posição automática. Quando `variant="plain"`, prioriza `top`; quando `variant="rich"`, prioriza `bottom-right`. `top-left`: No canto superior esquerdo. `top-start`: Acima, alinhado à esquerda. `top`: Acima, centralizado. `top-end`: Acima, alinhado à direita. `top-right`: No canto superior direito. `bottom-left`: No canto inferior esquerdo. `bottom-start`: Abaixo, alinhado à esquerda. `bottom`: Abaixo, centralizado. `bottom-end`: Abaixo, alinhado à direita. `bottom-right`: No canto inferior direito. `left-start`: À esquerda, alinhado ao topo. `left`: À esquerda, centralizado. `left-end`: À esquerda, alinhado à base. `right-start`: À direita, alinhado ao topo. `right`: À direita, centralizado. `right-end`: À direita, alinhado à base.
open-delay	openDelay	true	number	150	Atraso, em milissegundos, para exibir ao passar o mouse.
close-delay	closeDelay	true	number	150	Atraso, em milissegundos, para ocultar ao passar o mouse.
headline	headline	true	string		Título do tooltip. Disponível apenas quando `variant="rich"`. Também pode ser definido via `slot="headline"`.
content	content	true	string		Conteúdo do tooltip. Também pode ser definido via `slot="content"`.
trigger	trigger	true	'click' \| 'hover' \| 'focus' \| 'manual' \| string	'hover focus'	Forma de acionamento. Suporta múltiplos valores separados por espaço. Os valores possíveis são: `click`: Aciona ao clicar. `hover`: Aciona ao passar o mouse. `focus`: Aciona ao receber foco. `manual`: Só pode ser aberto e fechado programaticamente. Não pode ser combinado com outras formas de acionamento.
disabled	disabled	true	boolean	false	Define se o tooltip está desabilitado.
open	open	true	boolean	false	Define se o tooltip está visível.

### Eventos

Nome	Descrição
open	Disparado quando o tooltip começa a ser exibido. Pode impedir a abertura chamando `event.preventDefault()`.
opened	Disparado quando a animação de exibição do tooltip é concluída.
close	Disparado quando o tooltip começa a ser ocultado. Pode impedir o fechamento chamando `event.preventDefault()`.
closed	Disparado quando a animação de ocultação do tooltip é concluída.

### Slots

Nome	Descrição
(padrão)	Apenas o primeiro elemento do slot padrão será usado como elemento alvo.
headline	Título do tooltip. Só é válido quando `variant="rich"`.
content	Conteúdo do tooltip. Pode conter HTML. Se for apenas texto simples, pode-se usar o atributo `content` como alternativa.
action	Botões na parte inferior do tooltip. Só é válido quando `variant="rich"`.

### CSS Parts

Nome	Descrição
popup	Contêiner do tooltip.
headline	Título.
content	Corpo.
action	Botões de ação.

### Propriedades CSS personalizadas

Nome	Descrição
--shape-corner-plain	Tamanho da borda arredondada do componente quando `variant="plain"`. Pode ser um valor em pixels, mas é recomendado usar os design tokens.
--shape-corner-rich	Tamanho da borda arredondada do componente quando `variant="rich"`. Pode ser um valor em pixels, mas é recomendado usar os design tokens.
--z-index	Valor CSS `z-index` do componente.

# Componente TopAppBar A barra de aplicativo superior é usada para exibir informações e ações relacionadas no topo da página, fornecendo navegação clara e acesso conveniente às funcionalidades. ## Como usar {#usage} Importe os componentes conforme necessário: ```js import 'mdui/components/top-app-bar.js'; import 'mdui/components/top-app-bar-title.js'; ``` Importe os tipos TypeScript dos componentes conforme necessário: ```ts import type { TopAppBar } from 'mdui/components/top-app-bar.js'; import type { TopAppBarTitle } from 'mdui/components/top-app-bar-title.js'; ``` Exemplo de uso: (o `style="position: relative"` no exemplo é apenas para fins de demonstração; remova este estilo ao usar.) ```html

Title

``` **Observações:** Este componente usa `position: fixed` por padrão e adiciona automaticamente `padding-top` ao `body` para evitar que o conteúdo da página seja ocultado pelo componente. No entanto, nos dois casos a seguir, ele usará `position: absolute` por padrão: 1. Quando o atributo `scroll-target` é especificado. Assim, `padding-top` será adicionado no elemento `scroll-target`. 2. Quando o componente está dentro de [``](/pt-br/docs/2/components/layout). Assim, nenhum `padding-top` será adicionado. ## Exemplos {#examples} ### Dentro de um contêiner especificado {#example-scroll-target} Por padrão, a barra de aplicativo superior é exibida no topo da página, em relação à janela atual. Se você deseja colocar a barra de aplicativo superior dentro de um contêiner especificado, defina o atributo `scroll-target` no componente ``. O valor deve ser o seletor CSS ou elemento DOM do contêiner de conteúdo rolável. Assim, a barra de aplicativo superior será exibida em relação no elemento pai (você precisa adicionar os estilos `position: relative; overflow: hidden` no elemento pai). ```html

Title

``` ### Forma {#example-variant} Use o atributo `variant` no componente `` para definir a forma da barra de aplicativo superior. ```html

Title

center-aligned

small

medium

large

``` ### Comportamento ao rolar a página {#example-scroll-behavior} Definindo o atributo `scroll-behavior` no componente ``, você pode definir o comportamento da barra de aplicativo superior ao rolar a página. Você pode definir vários comportamentos separando-os por espaços. Os comportamentos de rolagem incluem: - `hide`: Oculta a barra de aplicativo superior ao rolar a página para baixo e a exibe ao rolar para cima. - `shrink`: Apenas efetivo quando o atributo `variant` é `medium` ou `large`. Expande a barra de aplicativo superior ao rolar para baixo e a contrai ao rolar para cima. - `elevate`: Adiciona sombra à barra de aplicativo superior ao rolar a página para baixo; remove a sombra quando a página volta ao topo. Use o atributo `scroll-threshold` para definir quantos pixels rolar antes de começar a acionar o comportamento da barra de aplicativo superior. (Observe que, para uma resposta rápida, ao usar o comportamento `elevate`, não defina o atributo `scroll-threshold`.) **Exemplo: Ocultar ao rolar** ```html

Title

``` **Exemplo: Adicionar sombra ao rolar** ```html

Title

``` **Exemplo: Contrair ao rolar** ```html

Title

``` **Exemplo: Contrair e adicionar sombra ao rolar** ```html

Title

``` ### Texto no estado expandido {#label-large} Para barras de aplicativo superior com `variant` `medium` ou `large` e `scroll-behavior` `shrink`, você pode adicionar o slot `label-large` no componente `` para definir o texto no estado expandido. ```html

Este é o título no estado recolhido Este é o título no estado expandido

``` ## mdui-top-app-bar-title API ### Slots

Nome	Descrição
(padrão)	Texto do título da barra de aplicativo superior.
label-large	Texto do título no estado expandido.

### CSS Parts

Nome	Descrição
label	Texto do título.
label-large	Texto do título no estado expandido.

## mdui-top-app-bar API ### Propriedades

Atributo	Propriedade	Reflect	Tipo	Padrão	Descrição
variant	variant	true	'center-aligned' \| 'small' \| 'medium' \| 'large'	'small'	Forma da barra de aplicativo superior. O padrão é `small`. Os valores possíveis são: `center-aligned`: Barra de aplicativo pequena, com título centralizado. `small`: Barra de aplicativo pequena. `medium`: Barra de aplicativo média. `large`: Barra de aplicativo grande.
hide	hide	true	boolean	false	Define se o componente está oculto.
shrink	shrink	true	boolean	false	Define se deve reduzir para o estilo `variant="small"`. Só é válido quando `variant="medium"` ou `variant="large"`.
scroll-behavior	scrollBehavior	true	'hide' \| 'shrink' \| 'elevate'		Comportamento de rolagem. Pode usar vários valores separados por espaço. Os valores possíveis são: `hide`: Ocultar ao rolar. `shrink`: Em barras de aplicativo médias e grandes, reduz ao estilo de barra pequena ao rolar. `elevate`: Adiciona sombra ao rolar.
scroll-target	scrollTarget	false	string \| HTMLElement \| JQ<HTMLElement>		O elemento no qual o evento de rolagem será monitorado. O valor pode ser um seletor CSS, um elemento DOM ou um objeto JQ. Por padrão, monitora o evento de rolagem da `window`.
scroll-threshold	scrollThreshold	true	number		A distância de rolagem, em `px`, necessária para acionar o comportamento.
order	order	true	number		A ordem de layout deste componente dentro do `<mdui-layout>`, em ordem crescente. O valor padrão é `0`.

### Eventos

Nome	Descrição
show	Disparado quando o componente começa a ser exibido. Pode impedir a exibição chamando `event.preventDefault()`.
shown	Disparado quando a animação de exibição é concluída.
hide	Disparado quando o componente começa a ser ocultado. Pode impedir a ocultação chamando `event.preventDefault()`.
hidden	Disparado quando a animação de ocultação é concluída.

### Slots

Nome	Descrição
(padrão)	Elementos dentro da barra de aplicativo superior.

### Propriedades CSS personalizadas

Nome	Descrição
--shape-corner	Tamanho da borda arredondada do componente. Pode ser um valor em pixels, mas é recomendado usar os design tokens.
--z-index	Valor CSS `z-index` do componente.

# Biblioteca de ferramentas jq O mdui possui uma biblioteca de ferramentas JavaScript leve que oferece API semelhante ao jQuery e encadeamento de métodos, mas com apenas um sexto do tamanho do jQuery. Você pode importar esta função de ferramenta sob demanda: ```js import { $ } from 'mdui/jq.js'; ``` ## Núcleo {#api-core} ### `$()` {#dollar} Esta função tem vários usos: Passar um seletor CSS como parâmetro retorna um objeto JQ contendo os elementos correspondentes. ```js $('.box'); ``` Passar um elemento DOM, qualquer array, NodeList ou objeto JQ retorna um objeto JQ contendo os elementos especificados. ```js $(document); ``` Passar uma string HTML retorna um objeto JQ contendo o DOM criado a partir do HTML. ```js $(`

`); ``` Passar uma função; a função será chamada quando o DOM terminar de carregar. ```js $(function () { console.log('DOM Carregado'); }); ``` ## Extensão {#api-extend} ### `$.extend()` {#d-extend} Se apenas um objeto for passado, as propriedades desse objeto serão mescladas no objeto `$`, o que equivale a adicionar novas funcionalidades ao namespace `$`. ```js $.extend({ customFunc: function () {}, }); // Então você pode chamar o método personalizado assim $.customFunc(); ``` Se dois ou mais objetos forem passados, as propriedades de todos os objetos serão adicionadas ao primeiro objeto e o objeto mesclado será retornado. Propriedades com valor `undefined` não são mescladas. ```js const object = $.extend({ key1: val1 }, { key2: val2 }, { key3: val3 }); // Agora o primeiro objeto e o valor retornado são { key1: val1, key2: val2, key3: val3 } ``` ### `$.fn.extend()` {#fn-extend} Estende métodos na cadeia de protótipos de `$`. ```js $.fn.extend({ customFunc: function () {}, }); // Então você pode usar o método estendido assim $(document).customFunc(); ``` ## URL {#api-url} ### `$.param()` {#d-param} Serializa um array ou objeto em uma string de consulta de URL. ```js $.param({ width: 1680, height: 1050 }); // width=1680&height=1050 $.param({ foo: { one: 1, two: 2 } }); // foo[one]=1&foo[two]=2 $.param({ ids: [1, 2, 3] }); // ids[]=1&ids[]=2&ids[]=3 ``` Se o parâmetro passado for um array, o formato desse array deve ser o mesmo retornado por [`.serializeArray()`](#serializeArray). ```js $.param([ { name: 'name', value: 'mdui' }, { name: 'password', value: '123456' }, ]); // name=mdui&password=123456 ``` ## Operações com arrays e objetos {#api-array} ### `$.each()` {#d-each} Itera sobre um array ou objeto. Ele retorna o primeiro parâmetro, ou seja, o array ou objeto iterado. O primeiro parâmetro da função de retorno é o índice do array ou a chave do objeto; o segundo parâmetro é o valor na posição correspondente do array ou objeto. Dentro da função de retorno, `this` aponta para o valor na posição correspondente do array ou objeto. Se a função de retorno retornar `false`, a iteração é interrompida. ```js // Iterar sobre um array $.each(['a', 'b', 'c'], function (index, value) { console.log(index + ':' + value); }); // Resultado: // 0:a // 1:b // 2:c ``` ```js // Iterar sobre um objeto $.each({ name: 'mdui', lang: 'zh' }, function (key, value) { console.log(key + ':' + value); }); // Resultado // name:mdui // lang:zh ``` ### `$.merge()` {#d-merge} Adiciona os elementos do segundo array ao primeiro array e retorna o array mesclado. ```js const first = ['a', 'b', 'c']; const second = ['c', 'd', 'e']; const result = $.merge(first, second); console.log(first); // ['a', 'b', 'c', 'c', 'd', 'e'] console.log(result); // ['a', 'b', 'c', 'c', 'd', 'e'] ``` ### `$.unique()` {#d-unique} Remove elementos duplicados de um array. ```js const result = $.unique([1, 2, 12, 3, 2, 1, 2, 1, 1, 1, 1]); console.log(result); // [1, 2, 12, 3] ``` ### `$.map()` {#d-map} Itera sobre um array ou objeto e retorna um novo array composto pelos valores retornados pela função de retorno. O primeiro parâmetro da função de retorno é o valor na posição correspondente do array ou objeto; o segundo parâmetro é o índice do array ou a chave do objeto. A função de retorno pode retornar qualquer valor. Se retornar um array, esse array será desmembrado. Se retornar `null` ou `undefined`, esse valor será ignorado. Dentro da função de retorno, `this` aponta para o objeto `window`. ```js // Iterar sobre um array const result = $.map(['a', 'b', 'c'], function (value, index) { return index + value; }); console.log(result); // ['0a', '1b', '2c'] ``` ```js // Quando a função de retorno retorna um array, o array é desmembrado const result = $.map([1, 2, 3], function (value, index) { return [value, value + 1]; }); console.log(result); // [1, 2, 2, 3, 3, 4] ``` ```js // Iterar sobre um objeto const result = $.map( { name: 'mdui', password: '123456' }, function (value, key) { return key + ':' + value; }, ); console.log(result); // ['name:mdui', 'password:123456'] ``` ### `$.contains()` {#d-contains} Determina se um nó contém outro nó. Se o nó pai contém o nó filho, retorna `true`; caso contrário, retorna `false`. ```js $.contains(document, document.body); // true $.contains(document.body, document); // false ``` ## Verificação de tipo de dados {#api-type} ### `.is()` {#is} Verifica se pelo menos um elemento na coleção corresponde ao parâmetro. Se corresponder, retorna `true`; caso contrário, retorna `false`. O parâmetro pode ser um seletor CSS, um elemento DOM, um array de elementos DOM, um objeto JQ ou uma função de retorno. Se o parâmetro for uma função de retorno, o primeiro parâmetro da função é o índice e o segundo é o elemento atual. Dentro da função, `this` aponta para o elemento atual. Se a função retornar `true`, significa que o elemento atual corresponde ao parâmetro; se retornar `false`, significa que não corresponde. ```js $('.box').is('.box'); // true $('.box').is('.boxss'); // false $('.box').is($('.box')[0]); // true ``` ```js // Julgar pelo valor retornado da função de retorno $(document).is(function (index, element) { return element === document; }); // true ``` ## Acesso a objetos {#api-object} ### `.length` {#length} Retorna o número de elementos na coleção atual. ```js $('body').length; // 1 ``` ### `.each()` {#each} Itera sobre a coleção atual, executando uma função para cada elemento. Se a função retornar `false`, a iteração é interrompida. O primeiro parâmetro da função é o índice do elemento; o segundo é o elemento atual. Dentro da função, `this` aponta para o elemento atual. ```js $('img').each(function (index, element) { this.src = 'test' + index + '.jpg'; }); ``` ### `.map()` {#map} Itera sobre a coleção atual, executando uma função para cada elemento e retorna uma nova coleção composta pelos valores retornados pela função. A função pode retornar um único dado ou um array de dados. Se retornar um array, os elementos do array serão adicionados sequencialmente à nova coleção. Se a função retornar `null` ou `undefined`, esse valor não será adicionado à nova coleção. O primeiro parâmetro da função é o índice do elemento; o segundo é o elemento atual. Dentro da função, `this` aponta para o elemento atual. ```js const result = $('input.checked').map(function (i, element) { return element.value; }); // result é um objeto JQ composto pelos valores dos elementos correspondentes ``` ### `.eq()` {#eq} Retorna uma nova coleção que contém apenas o elemento na posição de índice especificada. ```js $('div').eq(0); // Retorna uma coleção contendo apenas o primeiro elemento $('div').eq(-1); // Retorna uma coleção contendo apenas o último elemento $('div').eq(-2); // Retorna uma coleção contendo apenas o penúltimo elemento ``` ### `.first()` {#first} Retorna uma nova coleção que contém apenas o primeiro elemento da coleção atual. ```js $('div').first(); // Retorna uma coleção contendo apenas o primeiro div ``` ### `.last()` {#last} Retorna uma nova coleção que contém apenas o último elemento da coleção atual. ```js $('div').last(); // Retorna uma coleção contendo apenas o último div ``` ### `.get()` {#get} Retorna o elemento na posição de índice especificada. Se nenhum parâmetro for passado, retorna um array composto por todos os elementos da coleção. ```js $('div').get(); // Retorna um array com todos os elementos div $('div').get(0); // Retorna o primeiro elemento div $('div').get(-1); // Retorna o último elemento div ``` ### `.index()` {#index} Se nenhum parâmetro for passado, retorna o valor do índice do primeiro elemento da coleção atual em relação aos seus elementos irmãos. Se um seletor CSS for passado, retorna o valor do índice do primeiro elemento da coleção atual em relação aos elementos correspondentes ao seletor CSS. Se um elemento DOM for passado, retorna o valor do índice desse elemento na coleção atual. Se um objeto JQ for passado, retorna o valor do índice do primeiro elemento do objeto na coleção atual. ```html

``` ```js $('#child3').index(); // 2 $('#child3').index('#child div'); // 2 $('#child div').index($('#child3').get(0)); // 2 ``` ### `.slice()` {#slice} Retorna um subconjunto da coleção atual. Você pode especificar as posições inicial e final do subconjunto passando dois parâmetros (a posição final não é incluída). Se o segundo parâmetro não for passado, retorna todos os elementos da posição inicial até o final da coleção. ```js // Retorna todos os elementos após o terceiro (incluindo o terceiro) $('div').slice(3); // Retorna os elementos do terceiro ao quinto (incluindo o terceiro, excluindo o quinto) $('div').slice(3, 5); ``` ### `.filter()` {#filter} Filtra os elementos da coleção atual que correspondem à expressão especificada. O parâmetro pode ser um seletor CSS, um elemento DOM, um array de elementos DOM ou uma função de retorno. Se o parâmetro for uma função de retorno, o primeiro parâmetro da função é o índice do elemento; o segundo é o elemento atual. Dentro da função, `this` aponta para o elemento atual. Se a função retornar `true`, o elemento atual é mantido; se retornar `false`, o elemento atual é removido. ```js // Filtra todos os elementos div que contêm a classe .box $('div').filter('.box'); // Filtra todas as opções selecionadas $('#select option').filter(function (index, element) { return element.selected; }); ``` ### `.not()` {#not} Filtra os elementos da coleção atual que não correspondem à expressão especificada. O parâmetro pode ser um seletor CSS, um elemento DOM, um array de elementos DOM, um objeto JQ ou uma função de retorno que retorna um valor `boolean`. Se o parâmetro for uma função de retorno, o primeiro parâmetro da função é o índice do elemento; o segundo é o elemento atual. Dentro da função, `this` aponta para o elemento atual. Se a função retornar `true`, o elemento atual é removido; se retornar `false`, o elemento atual é mantido. ```js // Filtra todos os elementos div que não contêm a classe .box $('div').not('.box'); // Filtra todas as opções não selecionadas $('#select option').not(function (index, element) { return element.selected; }); ``` ## Classes CSS {#api-css} ### `.hasClass()` {#hasClass} Verifica se o primeiro elemento da coleção contém a classe CSS especificada. ```js // Verifica se o primeiro elemento div contém a classe .item $('div').hasClass('item'); ``` ### `.addClass()` {#addClass} Adiciona classes CSS a cada elemento da coleção. Múltiplos nomes de classe podem ser separados por espaços. O parâmetro pode ser uma string ou uma função de retorno que retorna nomes de classe CSS. Se o parâmetro for uma função de retorno, o primeiro parâmetro da função é o índice do elemento; o segundo são os nomes de classe CSS existentes no elemento. Dentro da função, `this` aponta para o elemento atual. ```js // Adiciona a classe .item a todos os elementos div $('div').addClass('item'); // Adiciona as classes .item1 e .item2 a todos os elementos div $('div').addClass('item1 item2'); // Adiciona classes CSS retornadas pela função de retorno a todos os elementos div $('div').addClass(function (index, currentClassName) { return currentClassName + '-' + index; }); ``` ### `.removeClass()` {#removeClass} Remove as classes CSS especificadas de cada elemento da coleção. Múltiplos nomes de classe podem ser separados por espaços. O parâmetro pode ser uma string ou uma função de retorno que retorna nomes de classe CSS. Se o parâmetro for uma função de retorno, o primeiro parâmetro da função é o índice do elemento; o segundo são os nomes de classe CSS existentes no elemento. Dentro da função, `this` aponta para o elemento atual. Se nenhum parâmetro for passado, este método remove diretamente o atributo `class` dos elementos. ```js // Remove a classe .item de todos os elementos div $('div').removeClass('item'); // Remove as classes .item1 e .item2 de todos os elementos div $('div').removeClass('item1 item2'); // Remove classes CSS retornadas pela função de retorno de todos os elementos div $('div').removeClass(function (index, currentClassName) { return 'item'; }); ``` ### `.toggleClass()` {#toggleClass} Se a classe CSS especificada existir no elemento, ela é removida; se não existir, é adicionada. Múltiplos nomes de classe podem ser separados por espaços. O parâmetro pode ser uma string ou uma função de retorno que retorna nomes de classe CSS. Se o parâmetro for uma função de retorno, o primeiro parâmetro da função é o índice do elemento; o segundo são os nomes de classe CSS existentes no elemento. Dentro da função, `this` aponta para o elemento atual. ```js // Alterna a classe .item em todos os elementos div $('div').toggleClass('item'); // Alterna as classes .item1 e .item2 em todos os elementos div $('div').toggleClass('item1 item2'); // Alterna classes CSS retornadas pela função de retorno em todos os elementos div $('div').toggleClass(function (index, currentClassName) { return 'item'; }); ``` ## Atributos de nós {#api-attr} ### `.prop()` {#prop} Obtém o valor da propriedade JavaScript do primeiro elemento da coleção. ```js // Obtém o valor da propriedade checked do primeiro elemento $('input').prop('checked'); ``` Se dois parâmetros forem passados, este método define o valor da propriedade JavaScript especificada para todos os elementos da coleção. O valor da propriedade pode ser qualquer tipo de valor ou o valor retornado por uma função de retorno. O primeiro parâmetro da função de retorno é o índice do elemento; o segundo é o valor original da propriedade no elemento. Dentro da função, `this` aponta para o elemento atual. Se o valor da propriedade ou o valor retornado pela função de retorno for `undefined`, este método não modificará a propriedade original do elemento. ```js // Define o valor da propriedade checked de todos os elementos selecionados como true $('input').prop('checked', true); // Define o valor da propriedade usando o valor retornado pela função de retorno $('input').prop('checked', function (index, oldPropValue) { return true; }); ``` Você também pode passar um objeto para definir várias propriedades simultaneamente. ```js // Define múltiplos valores de propriedade para os elementos simultaneamente $('input').prop({ checked: false, disabled: function (index, oldPropValue) { return true; }, }); ``` ### `.removeProp()` {#removeProp} Remove a propriedade JavaScript especificada de todos os elementos da coleção. ```js $('input').removeProp('disabled'); ``` ### `.attr()` {#attr} Obtém o valor do atributo HTML do primeiro elemento da coleção. ```js // Obtém o valor do atributo do primeiro elemento $('div').attr('username'); ``` Se dois parâmetros forem passados, este método define o valor do atributo HTML especificado para todos os elementos da coleção. O valor do atributo pode ser uma string ou número, ou um valor retornado por uma função de retorno. Se o parâmetro for uma função de retorno, o primeiro parâmetro da função é o índice do elemento; o segundo é o valor original do atributo no elemento. Dentro da função, `this` aponta para o elemento atual. Se o valor do atributo ou o valor retornado pela função de retorno for `null`, este método remove o atributo especificado; se for `undefined`, não modifica o atributo original do elemento. ```js // Define o valor do atributo para todos os elementos selecionados $('div').attr('username', 'mdui'); // Define o valor do atributo usando o valor retornado pela função de retorno $('div').attr('username', function (index, oldAttrValue) { return 'mdui'; }); ``` Você também pode passar um objeto para definir vários atributos simultaneamente. ```js // Define múltiplos valores de atributo para os elementos simultaneamente $('div').attr({ username: 'mdui', lastname: function (index, oldAttrValue) { return 'test'; }, }); ``` ### `.removeAttr()` {#removeAttr} Remove os atributos HTML especificados de todos os elementos da coleção. Múltiplos nomes de atributo podem ser separados por espaços. ```js // Remove um atributo de todos os elementos da coleção $('div').removeAttr('username'); // Remove múltiplos atributos de todos os elementos da coleção $('div').removeAttr('username lastname'); ``` ### `.val()` {#val} Retorna o valor do primeiro elemento da coleção. Se o elemento for ``, ``, `