# Introduction Let's begin by incorporating mdui into a basic page template using a CDN. > You are currently reading the documentation for mdui 2! > > For mdui 1 documentation, please visit [www.mdui.org/docs/](https://www.mdui.org/docs/). ## Getting Started {#getting-started} To use mdui, import the CSS and JS files from the CDN. For npm installation instructions, refer to the [Installation](/en/docs/2/getting-started/installation) section. **Importing Files** Add the following lines to your page's `` tag: ```html ``` To utilize the icon attribute (for example, `icon="search"` in ``), include the CSS file for the icon. Refer to [Using Material Icons](/en/docs/2/components/icon#usage-material-icons) for more information. mdui operates independently of third-party libraries and is ready to use once the files are included. ## Simplest Page Template {#template} Below is the simplest page template. You can add more components and content to build your website. ```html Hello, world! Hello, world! ``` # Installation mdui can be installed via npm or directly included from a CDN. The recommended method is npm. ## Install via npm {#npm} ```bash npm install mdui --save ``` ### Full Import {#full-import} To utilize all mdui components, import the following two files in your project's entry file: ```js import 'mdui/mdui.css'; import 'mdui'; ``` You can also import specific functions from mdui. For example, to import the [`snackbar`](/en/docs/2/functions/snackbar) function: ```js import { snackbar } from 'mdui'; ``` List all importable functions from mdui 
import {
  $,
  dialog,
  alert,
  confirm,
  prompt,
  snackbar,
  getTheme,
  setTheme,
  getColorFromImage,
  setColorScheme,
  removeColorScheme,
  loadLocale,
  setLocale,
  getLocale,
  throttle,
  observeResize,
  breakpoint
} from 'mdui';
 ### Cherry-picking Import {#cherry-picking} To optimize your project size, import only the necessary components and functions. For example, if you only need the [``](/en/docs/2/components/button) component and [`snackbar`](/en/docs/2/functions/snackbar) function, import them as follows: ```js // Always import the CSS file import 'mdui/mdui.css'; // Import the component import 'mdui/components/button.js'; // Import the snackbar function import { snackbar } from 'mdui/functions/snackbar.js'; ``` Each component or function documentation page provides details on how to cherry-pick imports. List all components and functions supported for cherry-picking import 
import 'mdui/components/avatar.js';
import 'mdui/components/badge.js';
import 'mdui/components/bottom-app-bar.js';
import 'mdui/components/button.js';
import 'mdui/components/button-icon.js';
import 'mdui/components/card.js';
import 'mdui/components/checkbox.js';
import 'mdui/components/chip.js';
import 'mdui/components/circular-progress.js';
import 'mdui/components/collapse/collapse.js';
import 'mdui/components/collapse/collapse-item.js';
import 'mdui/components/dialog.js';
import 'mdui/components/divider.js';
import 'mdui/components/dropdown.js';
import 'mdui/components/fab.js';
import 'mdui/components/icon.js';
import 'mdui/components/layout.js';
import 'mdui/components/layout-item.js';
import 'mdui/components/layout-main.js';
import 'mdui/components/linear-progress.js';
import 'mdui/components/list-item.js';
import 'mdui/components/list-subheader.js';
import 'mdui/components/list.js';
import 'mdui/components/menu-item.js';
import 'mdui/components/menu.js';
import 'mdui/components/navigation-bar-item.js';
import 'mdui/components/navigation-bar.js';
import 'mdui/components/navigation-drawer.js';
import 'mdui/components/navigation-rail.js';
import 'mdui/components/navigation-rail-item.js';
import 'mdui/components/radio.js';
import 'mdui/components/radio-group.js';
import 'mdui/components/range-slider.js';
import 'mdui/components/ripple.js';
import 'mdui/components/segmented-button.js';
import 'mdui/components/segmented-button-group.js';
import 'mdui/components/select.js';
import 'mdui/components/slider.js';
import 'mdui/components/snackbar.js';
import 'mdui/components/switch.js';
import 'mdui/components/tab.js';
import 'mdui/components/tab-panel.js';
import 'mdui/components/tabs.js';
import 'mdui/components/text-field.js';
import 'mdui/components/tooltip.js';
import 'mdui/components/top-app-bar-title.js';
import 'mdui/components/top-app-bar.js';
import { $ } from 'mdui/jq.js';
import { alert } from 'mdui/functions/alert.js';
import { breakpoint } from 'mdui/functions/breakpoint.js';
import { confirm } from 'mdui/functions/confirm.js';
import { dialog } from 'mdui/functions/dialog.js';
import { getColorFromImage } from 'mdui/functions/getColorFromImage.js';
import { getLocale } from 'mdui/functions/getLocale.js';
import { getTheme } from 'mdui/functions/getTheme.js';
import { loadLocale } from 'mdui/functions/loadLocale.js';
import { observeResize } from 'mdui/functions/observeResize.js';
import { prompt } from 'mdui/functions/prompt.js';
import { removeColorScheme } from 'mdui/functions/removeColorScheme.js';
import { setColorScheme } from 'mdui/functions/setColorScheme.js';
import { setLocale } from 'mdui/functions/setLocale.js';
import { setTheme } from 'mdui/functions/setTheme.js';
import { snackbar } from 'mdui/functions/snackbar.js';
import { throttle } from 'mdui/functions/throttle.js';
 ## CDN {#cdn} mdui can also be included directly via a CDN using `` and ` Click me ``` ### ES Module Build {#es-module} The ES module build of mdui allows you to import it using ES module syntax from the CDN. ```html Click me ``` # Usage mdui components, as standard Web Components, can be used like `
` elements. Each component's documentation provides a comprehensive API, including attributes, methods, events, slots, CSS parts, and CSS custom properties. This guide focuses on the usage of Web Components. ## Attributes {#attribute} Attributes are divided into HTML attributes and JavaScript properties. They usually correspond one-to-one and are synchronized. This means that updating an HTML attribute value also updates the JavaScript property value, and vice versa. HTML attributes can be set directly in the component's HTML string. They can be read or modified using the `getAttribute` and `setAttribute` methods: ```html Click me ``` JavaScript properties can be accessed directly on the component instance or set to modify the property value: ```html Click me ``` Some attributes are boolean. The corresponding JavaScript property is `true` when the HTML attribute exists and `false` otherwise. However, mdui treats the string value `false` as equivalent to the boolean value `false` for compatibility with certain frameworks. ```html ``` For properties that are arrays, objects, or functions, there is only a JavaScript property, and no corresponding HTML attribute. For example, the [``](/en/docs/2/components/slider) component's [`labelFormatter`](/en/docs/2/components/slider#attributes-labelFormatter) property is a function, which can only be set using JavaScript property: ```html ``` Here's an example from the attribute documentation of the [``](/en/docs/2/components/slider) component: | HTML Attribute | JavaScript Property | reflect | | -------------- | ------------------- | -------------------------------------------------------------------------------------- | | `name` | `name` | | | `value` | `value` | | | | `labelFormatter` | | The `name` attribute of this component has both HTML and JavaScript properties, and the reflect column indicates that if the JavaScript property is updated, the HTML attribute will also be updated. However, the `value` attribute does not reflect changes from the JavaScript property to the HTML attribute. The `labelFormatter` property only exists as a JavaScript property. ## Methods {#method} Components provide public methods that trigger specific behaviors. For example, the [`focus()`](/en/docs/2/components/text-field#methods-focus) method of the [``](/en/docs/2/components/text-field) component sets the focus on the text field. ```html ``` Please refer to the individual documentation of each component for a comprehensive list of methods and their parameters. ## Events {#event} Components emit events in response to specific actions. For example, the [``](/en/docs/2/components/dialog) component emits an [`open`](/en/docs/2/components/dialog#events-open) event when it begins to open. These events can be listened to, enabling the execution of custom actions. ```html Dialog ``` A comprehensive list of events and their parameters for each component can be found in their respective documentation pages. When integrating mdui with other frameworks such as Vue, React, or Angular, you can use the framework's syntax to bind events. However, some frameworks, like React, may only support standard events like `click` and not custom events like `open`. In these cases, you may need to manually bind the event using `addEventListener` by obtaining a reference to the element. For more information on using mdui with React, please refer to the [Frameworks - React](/en/docs/2/frameworks/react) section. ## Slot {#slot} Components often provide slots for inserting custom HTML content. The default slot is the most common, used for plain HTML or text within the component. For example, the default slot of the [``](/en/docs/2/components/button) component sets the button's text: ```html Click me ``` Some components also offer named slots. You should specify the slot name in the HTML's `slot` attribute. For example, the [``](/en/docs/2/components/icon) component uses `slot="start"` to indicate a named slot called [`start`](/en/docs/2/components/button#slots-icon), positioning the icon on the left inside the component: ```html Settings ``` For components with multiple named slots, the order doesn't matter. They just need to be inside the component, and the browser will automatically place them in the correct positions. Refer to each component's documentation for a list of supported slots. ## CSS Custom Properties {#css-custom-properties} mdui utilizes CSS Custom Properties, also known as CSS variables, to establish a series of [global design tokens](/en/docs/2/styles/design-tokens). These tokens are referenced by various components, enabling you to adjust the styles of mdui components globally. For example, you can reduce the corner radius of all components by modifying the relevant CSS custom properties: ```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; } ``` CSS custom properties can also be adjusted within a local scope. For example, you can reduce the corner radius for elements with the `class="sharp"` and their child elements by setting the appropriate CSS custom properties: ```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; } ``` Certain components also provide unique CSS custom properties. These are scoped to specific components and do not include the `--mdui` prefix. For example, you can modify the `z-index` style of the [``](/en/docs/2/components/dialog) component by adjusting its `--z-index` property. ```css mdui-dialog { --z-index: 3000; } ``` Please refer to the documentation of each component for a list of supported CSS custom properties. ## CSS Part {#css-part} mdui components utilize the shadow DOM for encapsulating styles and behaviors. However, standard CSS selectors cannot select elements within the shadow DOM. To overcome this, some components add a `part` attribute to elements within the shadow DOM. These elements can then be selected and styled using the `::part` CSS selector. For example, the [`button`](/en/docs/2/components/button#cssParts-button) part modifies the inner padding of the button, while the [`label`](/en/docs/2/components/button#cssParts-label), [`icon`](/en/docs/2/components/button#cssParts-icon), and [`end-icon`](/en/docs/2/components/button#cssParts-end-icon) parts adjust the text color, left icon color, and right icon color, respectively: ```html Button ``` To understand the structure and default styles of component shadow DOM elements, you can inspect them using your browser's developer tools. Before using CSS Part, consider whether global CSS custom properties and component-specific CSS custom properties can meet your needs. If they can, it's recommended to use CSS custom properties for style customization. For a list of publicly exposed `part` properties, please refer to the documentation of each component. ## Component Update Mechanism {#update-mechanism} mdui components are built using [Lit](https://lit.dev/), a lightweight library that streamlines the development of Web Components. Understanding the rendering and update mechanism of the components can enhance your experience when using mdui components. When you modify the properties of mdui components, the components will re-render. However, this re-rendering is not synchronous. When multiple property values change at the same time, Lit buffers these changes until the next update cycle. This approach ensures that each component re-renders only once, regardless of the number of property changes. Only the parts of the shadow DOM where changes have occurred will be re-rendered. In the example below, we set the `disabled` JavaScript property of a button to `true` and immediately query its HTML attribute. However, the component hasn't had a chance to re-render yet, so the queried HTML attribute remains `false`: ```js const button = document.querySelector('mdui-button'); button.disabled = true; console.log(button.hasAttribute('disabled')); // false ``` To ensure a component has completed re-rendering after a property value change, you can use the `updateComplete` property. This property returns a Promise that resolves once the component finishes re-rendering. ```js const button = document.querySelector('mdui-button'); button.disabled = true; button.updateComplete.then(() => { console.log(button.hasAttribute('disabled')); // true }); ``` # TypeScript Support mdui is developed with TypeScript, offering robust TypeScript support. All official mdui libraries include type declaration files for immediate use. ## Component Instance Types {#instance} Occasionally, you may need to assert a JavaScript variable as an mdui component instance. You can import the corresponding component type directly from mdui. For example, to import the Tooltip component type from the component file: ```ts import type { Tooltip } from 'mdui/components/tooltip.js'; ``` Alternatively, import the Tooltip component type directly from mdui: ```ts import type { Tooltip } from 'mdui'; ``` Then, you can assert a JavaScript variable as the Tooltip type: ```ts const tooltip = document.querySelector('mdui-tooltip') as Tooltip; ``` Your IDE will automatically suggest the properties and methods of the `tooltip` variable. When adding an event listener to the `tooltip` variable, the IDE will also suggest event names, event types, and the `this` context in the callback function: ```ts tooltip.addEventListener('open', function(event) { }); ``` ## Event Types {#event} Each component exports an interface mapping the component's event names to their corresponding event object types. The interface is named `${componentName}EventMap`. For example, the Tooltip component exports an interface named `TooltipEventMap`: ```ts export interface TooltipEventMap { open: CustomEvent; opened: CustomEvent; close: CustomEvent; closed: CustomEvent; } ``` You can import the `TooltipEventMap` interface from the component file: ```ts import type { TooltipEventMap } from 'mdui/components/tooltip.js'; ``` Or directly from mdui: ```ts import type { TooltipEventMap } from 'mdui'; ``` This interface only includes component-specific events. Since mdui components inherit from `HTMLElement`, they also support `HTMLElement` events. Use intersection types to get all event types for a component: ```ts type TooltipAndHTMLElementEventMap = TooltipEventMap & HTMLElementEventMap; ``` # IDE Support mdui is optimized for VS Code and WebStorm, offering features such as code autocompletion and hover hints. ## VS Code {#vscode} ### For npm-installed mdui {#vscode-npm} If you've installed mdui via npm, you can enable VS Code IDE support for your project by following these steps: 1. Create a `.vscode` directory at your project root. 2. Inside the `.vscode` directory, create a `settings.json` file. 3. Add the following code to `settings.json`: ```json { "html.customData": ["./node_modules/mdui/html-data.en.json"], "css.customData": ["./node_modules/mdui/css-data.en.json"] } ``` If `settings.json` already exists, simply add the above lines to the root of the JSON document. Restart VS Code after making these changes. ### For mdui Used via CDN {#vscode-cdn} If you're using mdui through a CDN, you can install the mdui VS Code extension for IDE support. Search for `mdui` in the VS Code extension marketplace, select the first result and install it, or [click here to install](vscode:extension/zdhxiong.mdui). This will enable mdui IDE support for all projects. Prioritize npm installation and `settings.json` setup over the VS Code extension to ensure IDE support aligns with the mdui version in use. WebStorm {#webstorm} ## WebStorm {#webstorm} ### For npm-installed mdui {#webstorm-npm} To enable WebStorm IDE support for mdui installed via npm: 1. Add the following code to the root of your project's `package.json` file: ``` web-types: ["./node_modules/mdui/web-types.en.json"] ``` If `package.json` already has a `web-types` property, add `./node_modules/mdui/web-types.en.json` to the `web-types` array. Restart WebStorm after these changes. ### For mdui Used via CDN {#webstorm-cdn} If you're using mdui through a CDN, you can install the mdui WebStorm plugin for IDE support. Search for `mdui` in the WebStorm plugin marketplace, select the first result and install it. This will enable mdui IDE support for all projects. Prioritize npm installation and `package.json` setup over the WebStorm plugin to ensure IDE support aligns with the mdui version in use. ## Differences in VS Code and WebStorm Support {#difference} mdui support varies between VS Code and WebStorm. The table below details the differences: | Code Autocompletion and Hover Hints Location | VS Code | WebStorm | | ------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | HTML tag names | | | | Attribute names within HTML tags | | | | Enumeration values within HTML tag attributes | | (Does not support displaying enumeration value comments) | | Event names within HTML tags | | | | `name` attribute values within HTML slots | | | | `part` attribute names within CSS `::part()` selectors | | (Requires WebStorm 2023.2 or later) | | CSS custom property names within component-specific CSS | | | | Global CSS custom property names | | | | Global CSS class names | | | # Localization mdui uses English by default. If you wish to use other languages, you'll need to do some localization configuration. ## Usage {#usage} mdui provides three functions for localization: * [`loadLocale`](/en/docs/2/functions/loadLocale): Loads locale modules. Accepts a function that takes a locale code and returns a Promise resolving to the locale module. Ensure to call this function in your project's entry file. * [`setLocale`](/en/docs/2/functions/setLocale): Begins switching the active locale to the given locale code, and returns a promise that resolves when the new locale has loaded. * [`getLocale`](/en/docs/2/functions/getLocale): Returns the active locale code. Example usage: ```js import { loadLocale } from 'mdui/functions/loadLocale.js'; import { setLocale } from 'mdui/functions/setLocale.js'; import { getLocale } from 'mdui/functions/getLocale.js'; // Load locale modules in the entry point of your project loadLocale((locale) => import(`../node_modules/mdui/locales/${locale}.js`)); // Switch locale, and returns a promise that resolves when the new locale has loaded setLocale('zh-cn').then(() => { // You can use getLocale() to get the current locale code console.log(getLocale()); // zh-cn }); ``` ## Status Events {#event} The `mdui-localize-status` event fires on `window` whenever a locale switch starts, finishes, or fails. You can listen to this event to execute custom operations, such as setting a locale preference cookie. The `detail.status` string property tells you what kind of status change has occured, and can be either `loading`, `ready`, or `error`:
detail.status description
loading

A new locale has started to load.

The detail object contains:

  • loadingLocale: Code of the locale that has started loading.
ready

A new locale has successfully loaded.

The detail object contains:

  • readyLocale: Code of the locale that has successfully loaded.
error

A new locale failed to load.

The detail object contains:

  • errorLocale: Code of the locale that failed to load.
  • errorMessage: Error message from locale load failure.
Example of using the status event: ```js window.addEventListener('mdui-localize-status', (event) => { if (event.detail.status === 'loading') { console.log(`Loading new locale: ${event.detail.loadingLocale}`); } else if (event.detail.status === 'ready') { console.log(`Loaded new locale: ${event.detail.readyLocale}`); } else if (event.detail.status === 'error') { console.error(`Error loading locale ${event.detail.errorLocale}: ${event.detail.errorMessage}`); } }); ``` ## Approaches for loading locale modules {#load-locale} ### Lazy-load {#lazy-load} Use [dynamic imports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) to load each locale only when it becomes active. This is a good default because it minimizes the amount of code that your users will download and execute. ```js import { loadLocale } from 'mdui/functions/loadLocale.js'; loadLocale((locale) => import(`../node_modules/mdui/locales/${locale}.js`)); ``` ### Pre-load {#pre-load} Start pre-loading all locales when the page loads. Dynamic imports are still used to ensure that the remaining script on the page is not blocked while the locale modules are being fetched. ```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)); ``` ### Static imports {#static-imports} Use [static imports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) to pre-load all locales in a way that blocks other script on the page. ```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)); ``` ## Loading Locale Modules via CDN {#cdn} When using mdui via CDN, you can directly load locale modules from the CDN: ```html ``` ## Supported Languages {#languages} mdui supports the following locales: | Language | Locale Code | | ------------------------ | ----------- | | Arabic | ar-eg | | Azerbaijani | az-az | | Bulgarian | bg-bg | | Bangla (Bangladesh) | bn-bd | | Belarusian | be-by | | Catalan | ca-es | | Czech | cs-cz | | Danish | da-dk | | German | de-de | | Greek | el-gr | | English (United Kingdom) | en-gb | | English | en-us | | Spanish | es-es | | Estonian | et-ee | | Persian | fa-ir | | Finnish | fi-fi | | French (Belgium) | fr-be | | French (Canada) | fr-ca | | French (France) | fr-fr | | Irish (Ireland) | ga-ie | | Galician (Spain) | gl-es | | Hebrew | he-il | | Hindi | hi-in | | Croatian | hr-hr | | Hungarian | hu-hu | | Armenian | hy-am | | Indonesian | id-id | | Italian | it-it | | Icelandic | is-is | | Japanese | ja-jp | | Georgian | ka-ge | | Khmer | km-kh | | Kurdish (Kurmanji) | kmr-iq | | Kannada | kn-in | | Kazakh | kk-kz | | Korean | ko-kr | | Lithuanian | lt-lt | | Latvian | lv-lv | | Macedonian | mk-mk | | Malayalam (India) | ml-in | | Mongolian | mn-mn | | Malay (Malaysia) | ms-my | | Norwegian | nb-no | | Nepal | ne-np | | Dutch (Belgium) | nl-be | | Dutch | nl-nl | | Polish | pl-pl | | Portuguese (Brazil) | pt-br | | Portuguese | pt-pt | | Romanian | ro-ro | | Russian | ru-ru | | Slovak | sk-sk | | Serbian | sr-rs | | Slovenian | sl-si | | Swedish | sv-se | | Tamil | ta-in | | Thai | th-th | | Turkish | tr-tr | | Urdu (Pakistan) | ur-pk | | Ukrainian | uk-ua | | Vietnamese | vi-vn | | Chinese (Simplified) | zh-cn | | Chinese (Traditional) | zh-hk | | Chinese (Traditional) | zh-tw | ## Submitting New Translations or Improvements {#contribute} To contribute new translations or improvements to existing translations, please submit a pull request on GitHub. Translations are located in [`packages/mdui/src/xliff`](https://github.com/zdhxiong/mdui/tree/v2/packages/mdui/src/xliff) and can be edited directly on GitHub if you don’t want to clone the repo locally. # Frequently Asked Questions ## Why Don't Components Display with Self-Closing Tags? {#no-self-closing} mdui is a library based on Web Components. Web Components do not support self-closing tags, so you should always use closing tags with mdui components. ```html ``` ## How to Prevent Unstyled Components Display Before Loading? {#waiting-load} mdui components are registered via JavaScript, which may cause a brief unstyled display until the JavaScript loads and registers the components. Here are two solutions: One solution is to use the [`:defined`](https://developer.mozilla.org/zh-CN/docs/Web/CSS/:defined) pseudo-class to hide unregistered mdui components. The following CSS hides all unregistered mdui components and shows them once registered: ```css :not(:defined) { visibility: hidden; } ``` Another solution is to use the [`customElements.whenDefined()`](https://developer.mozilla.org/zh-CN/docs/Web/API/CustomElementRegistry/whenDefined) method. This method returns a promise that resolves when the specified component is registered. To handle cases where some components may fail to load, use [`Promise.allSettled()`](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled). In the following example, the `` element is initially hidden using `opacity: 0` and fades in after the components are registered. `Promise.allSettled()` is used to wait for all promises to complete, ensuring the page displays properly even if a component fails to load. ```html ``` # LLMs.txt mdui provides two files: `llms.txt` and `llms-full.txt`. They give large language models (LLMs) accurate, citable context so the model can answer mdui questions more reliably. ## Use llms.txt to provide context to AI {#context} Links: - `llms.txt`: https://www.mdui.org/en/docs/2/llms.txt - `llms-full.txt`: https://www.mdui.org/en/docs/2/llms-full.txt `llms.txt` is a short index. It is good for models that can browse the web. They can follow the links to fetch the needed Markdown pages, or use it as a quick project overview. `llms-full.txt` contains the full context. It includes all page contents listed by `llms.txt`. Use it when the model cannot access the internet or when you want to provide everything in one file. ## Markdown versions of the docs {#md-mirror} Every docs page has a Markdown version. Append `.md` to the page URL (append `index.md` for the home page). Examples: https://www.mdui.org/en/docs/2/components/button → https://www.mdui.org/en/docs/2/components/button.md https://www.mdui.org/en/docs/2/ → https://www.mdui.org/en/docs/2/index.md You can give the Markdown URL or paste its plain text as context. This often produces more focused and accurate answers. ## How to use with ChatGPT, Claude, etc. {#how-to-use} Choose a method based on whether the model can browse or upload files (you can also combine them): 1. Paste directly: put the content of `llms-full.txt` in the system prompt or the first message. Example: "Here is the mdui context. Answer strictly based on it. If there is a conflict, this context takes precedence:\n\n[paste llms-full.txt here]". 2. Upload a file: upload `llms-full.txt` (or `llms.txt`) and say in the first message: "Use the attachment as the main context". Example: "Based on the attached mdui docs, describe how to use `` and list common pitfalls." 3. Read online: send a link to `llms.txt` or `llms-full.txt`. Example: "Please load and follow https://www.mdui.org/en/docs/2/llms-full.txt as context for my mdui questions." 4. Point to a specific page: if you only need one component or function, send that page’s Markdown URL. Example: "Please read https://www.mdui.org/en/docs/2/components/button.md and give three best practices based on it." Tip: Click the icon at the top right of any page to quickly copy these links, open the Markdown version, or open the current page or `llms-full.txt` in ChatGPT as context. # Dark Theme All mdui components support dark mode and can automatically switch themes based on the operating system's settings. Switch between light and dark themes by clicking the icons in the top right corner of the documentation page. This allows you to preview component appearance in different themes. To enable dark mode, add the `mdui-theme-dark` class to the `` tag: ```html ``` For automatic theme switching based on the operating system settings, use the `mdui-theme-auto` class: ```html ``` You can apply different themes to different containers within a page. For example, the following example sets dark mode on the `` tag, but a nested `
` uses the `mdui-theme-light` class. As a result, elements within this div display in light mode, while the rest of the page remains in dark mode: ```html
``` mdui also provides two functions for convenient theme manipulation: * [`getTheme`](/en/docs/2/functions/getTheme): Retrieves the current theme on the entire page or a specified element. * [`setTheme`](/en/docs/2/functions/setTheme): Applies a theme to the entire page or a specified element. ---- Note: mdui sets `color` and `background-color` styles on `:root`, `.mdui-theme-light`, `.mdui-theme-dark`, and `.mdui-theme-auto` selectors. If you prefer different styles, feel free to override these defaults. For example, to set the background color to pure white and text color to pure black in light mode, and vice versa in dark mode, use the following CSS: ```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; } } ``` # Dynamic Theme mdui supports dynamic theming. By providing a color value, mdui generates a comprehensive color scheme. It can also extract the dominant color from a wallpaper and create a color scheme based on it. Click the palette icon in the top right corner of the documentation page to toggle between color schemes and observe the appearance of various components under different color schemes. A color scheme in mdui is a set of CSS custom properties. mdui components reference these properties for their color values, enabling you to update the entire color scheme simultaneously. Refer to [Design Tokens - Color](/en/docs/2/styles/design-tokens#color) for a complete list of CSS custom properties. ## Generating a Color Scheme {#color-scheme} The [`setColorScheme`](/en/docs/2/functions/setColorScheme) function generates a color scheme. It accepts a hexadecimal color value, generates a color scheme based on it, and applies it to the `` element of the page. For example: ```js import { setColorScheme } from 'mdui/functions/setColorScheme.js'; // Generate a color scheme based on #0061a4 and set the element to that color scheme setColorScheme('#0061a4'); ``` You can specify the `target` property in the second parameter to apply the color scheme to a specific element. For example: ```js import { setColorScheme } from 'mdui/functions/setColorScheme.js'; // Generate a color scheme based on #0061a4 and apply it to the .foo element setColorScheme('#0061a4', { target: document.querySelector('.foo') }); ``` By default, the generated color scheme includes only the colors listed in [Design Tokens - Color](/en/docs/2/styles/design-tokens#color). You can include custom color groups by specifying the `customColors` property in the second parameter. Provide your custom color names and values as shown: ```js import { setColorScheme } from 'mdui/functions/setColorScheme.js'; // Generate a color scheme based on #0061a4, modify the value of the existing error color group, and add a new music color group setColorScheme('#0061a4', { customColors: [ { name: 'error', value: '#69F0AE' }, { name: 'music', value: '#FFC107' } ] }); ``` A custom color group includes four CSS custom properties: * `--mdui-color-{name}` * `--mdui-color-on-{name}` * `--mdui-color-{name}-container` * `--mdui-color-on-{name}-container` Here, `{name}` is the custom color `name` you provided in the `customColors` field. Custom color names can be existing color names from the default color scheme, such as `primary`, `secondary`, `tertiary`, `error`, etc. If you specify these values as custom color names, the corresponding four CSS custom properties in the generated color scheme will use the color values you specified. For example, in the above example, the custom color name `error` is specified, and since `error` is an existing color name in the default color scheme, its corresponding CSS custom properties are used by mdui components to represent error states. Now, because the color value is set to a green color, the error state in mdui components will also become green. Custom color names can also be new ones, such as `music` in the above example, which does not exist in the default color scheme. In this case, the generated color scheme will additionally include four CSS custom properties. You can reference these CSS custom properties in your own styles: ```html
Music
Music Container
``` You can also use the [`removeColorScheme`](/en/docs/2/functions/removeColorScheme) function to remove a color scheme. Specify a parameter to remove the color scheme from a specific element. By default, it removes the color scheme from the `` element. ## Extracting Colors from Wallpaper {#from-wallpaper} The [`getColorFromImage`](/en/docs/2/functions/getColorFromImage) function in mdui extracts the dominant color from an Image instance. This function returns a Promise that resolves to the extracted hexadecimal color value. You can use this color value with the [`setColorScheme`](/en/docs/2/functions/setColorScheme) function to set the color scheme. For example: ```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)); ``` # Typography mdui offers the `mdui-prose` CSS class for enhancing the styling of articles and the `mdui-table` CSS class for improving table styles. ## Article Styling {#prose} To enhance the overall visual presentation of an article, including `` elements, apply the `mdui-prose` class to the parent element of the article: ```html

Heading

Body

``` ## Table Styling {#table} To improve the visual presentation of a table, apply the `mdui-table` class to the `` element: ```html
``` For horizontal scrolling within an element, apply the `mdui-table` class to the parent element of the ``: ```html
``` # Design Tokens Design Tokens are a strategy employed in managing design systems. They abstract reusable elements such as colors, fonts, and spacing into independent variables. These variables are then consistently used across the design system. mdui employs global CSS custom properties to implement Design Tokens, ensuring style consistency across all components. By modifying these properties, you can globally adjust the styles of all mdui components. For your own styles, prioritize using these CSS custom properties to maintain consistency with mdui component styles. This also ensures your styles update synchronously when modifying dynamic color schemes. ## Color {#color} mdui provides CSS custom properties for both light and dark modes. In light mode, the property is named `--mdui-color-{name}-light`, and in dark mode, it's `--mdui-color-{name}-dark`. Additionally, mdui provides CSS custom properties named `--mdui-color-{name}`. This property references `--mdui-color-{name}-light` in light mode and `--mdui-color-{name}-dark` in dark mode, enabling automatic color switching based on the current mode. To modify specific colors, adjust both `--mdui-color-{name}-light` and `--mdui-color-{name}-dark`. When reading CSS custom properties, use the `--mdui-color-{name}` property. The values of CSS custom properties are three RGB colors separated by `,`. Here's an example of how to use color CSS custom properties: ```css /* Modify the color value of primary */ :root { --mdui-color-primary-light: 103, 80, 164; --mdui-color-primary-dark: 208, 188, 255; } /* Set the background color of the foo element to primary */ .foo { background-color: rgb(var(--mdui-color-primary)); } /* Set the background color of the bar element to primary with 0.8 opacity */ .bar { background-color: rgba(var(--mdui-color-primary), 0.8); } ``` For creating a completely new color scheme, consider using the [`setColorScheme`](/en/docs/2/functions/setColorScheme) function. This function generates a complete color scheme based on the provided color.
Color Name CSS Custom Property Default Example
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
## Corner Radius {#shape-corner} mdui provides 7 corner radius sizes. These CSS custom properties allow you to adjust the corner radius: ```css /* Modify the corner radius size of extra-smal */ :root { --mdui-shape-corner-extra-small: 0.3rem; } /* Set the corner radius of the foo element to extra-small */ .foo { border-radius: var(--mdui-shape-corner-extra-small); } ``` | CSS Custom Property | Default | Example | | --------------------------------- | --------- | --------------------------------------------------------------------------------------------------------- | | `--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` |
| ## Typography {#typescale} mdui provides 15 typography styles. Each style includes properties for line height, font size, letter spacing, and font weight. Here's an example of how to use these properties: ```css /* Modify the text style of 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; } /* Set the text style of the foo element to 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); } ```
CSS Custom Property Default Example
--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
## State Layer Opacity {#state-layer} mdui components, such as [``](/en/docs/2/components/button), utilize a semi-transparent overlay layer during interaction states like hover, focus, press, and drag. The opacity of this layer can be adjusted by modifying the following CSS custom properties: ```css /* Modify the opacity of the state layer */ :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; } ``` | CSS Custom Property | Default | Example | | ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------------ | | `--mdui-state-layer-hover` | `0.08` |
| | `--mdui-state-layer-focus` | `0.12` |
| | `--mdui-state-layer-pressed` | `0.12` |
| | `--mdui-state-layer-dragged` | `0.16` |
| ## Elevation {#elevation} mdui components use elevation to create depth with shadows. You can adjust these shadows by modifying the CSS custom properties: ```css /* Modify the elevation of level1 */ :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%); } /* Set the elevation of the foo element to level1 */ .foo { box-shadow: var(--mdui-elevation-level1); } ``` | CSS Custom Property | Default | Example | | ------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `--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%)` |
| ## Animation {#motion} mdui components incorporate animations, with customizable easing curves and durations. These properties can be adjusted using CSS custom properties: ```css /* Modify the standard easing curve and short1 duration */ :root { --mdui-motion-easing-standard: cubic-bezier(0.2, 0, 0, 1); --mdui-motion-duration-short1: 40ms; } /* Apply the standard easing curve and short1 duration to the transition effect of the foo element */ .foo { transition: all var(--mdui-motion-duration-short1) var(--mdui-motion-easing-standard); } ```
Type CSS Custom Property Default
Easing Curve --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)
Duration --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
## Breakpoint {#breakpoint} mdui components adjust their layout based on various breakpoints, which are provided through CSS custom properties. Here's an example of how to modify a breakpoint: ```css /* Modify the breakpoint value for sm */ :root { --mdui-breakpoint-sm: 560px; } ``` Please note that CSS custom properties cannot be used in CSS media queries. For example, the following usage is incorrect: ```css /* Incorrect usage. CSS custom properties cannot be used in media queries */ @media (min-width: var(--mdui-breakpoint-sm)) { } ``` To determine breakpoints in JavaScript, use the [`breakpoint`](/en/docs/2/functions/breakpoint) function. | CSS Custom Property | Default | | ----------------------- | -------- | | `--mdui-breakpoint-xs` | `0px` | | `--mdui-breakpoint-sm` | `600px` | | `--mdui-breakpoint-md` | `840px` | | `--mdui-breakpoint-lg` | `1080px` | | `--mdui-breakpoint-xl` | `1440px` | | `--mdui-breakpoint-xxl` | `1920px` | # Integrate with React To integrate mdui with React, start by following the steps on the [installation](/en/docs/2/getting-started/installation#npm) page. ## Notes {#notes} When using mdui in a React environment, there are certain aspects to be aware of. These considerations stem from the general constraints of Web Components and are not specific to mdui. ### Event Binding {#event-binding} React does not natively support custom events. Therefore, to utilize events provided by mdui components, it's necessary to obtain a reference to the component using the `ref` attribute. This reference can then be used to add event listeners. Here's an example of handling mdui component events in 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; ``` ### TypeScript Type Declarations for JSX {#jsx-typescript} If you're using mdui in TypeScript files (.tsx), it's important to include TypeScript type declarations. You can do this by importing mdui's type declaration files into your project's .d.ts file: ```ts /// ``` # Integrate with Vue After completing the [installation](/en/docs/2/getting-started/installation#npm) of mdui in Vue, you'll need to perform some additional configurations. ## Configuration {#configuration} To prevent Vue from interpreting mdui components as Vue components, you'll need to adjust the `compilerOptions.isCustomElement` option in the `vite.config file`: ```js // vite.config.js import vue from '@vitejs/plugin-vue' export default { plugins: [ vue({ template: { compilerOptions: { // Treat all tags starting with mdui- as mdui components isCustomElement: (tag) => tag.startsWith('mdui-') } } }) ] } ``` For more information, please refer to the [Vue official documentation](https://cn.vuejs.org/guide/extras/web-components.html#using-custom-elements-in-vue). ## Notes {#notes} ### Two-way Data Binding {#data-binding} The `v-model` directive cannot be used for two-way data binding with mdui components. Instead, you'll need to manually manage data binding and updates. For example: ```html ``` ### eslint Configuration {#eslint} If you're using [`eslint-plugin-vue`](https://www.npmjs.com/package/eslint-plugin-vue), you'll need to add the following rule to your `.eslintrc.js`: ```js rules: { 'vue/no-deprecated-slot-attribute': 'off' } ``` # Integrate with Angular To utilize mdui in Angular, you must first complete the [installation](/en/docs/2/getting-started/installation#npm) of mdui. Following this, additional configuration is required. ## Configuration {#configuration} The first step is to enable the use of Web Components in Angular. This can be achieved by adding the `CUSTOM_ELEMENTS_SCHEMA` to the `schemas` array in your module. ```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 {} ``` Once this is set up, you can import mdui components into your Angular component code. ```js import { Dialog } from 'mdui/components/dialog.js'; @Component({ selector: 'app-dialog-example', template: `
Dialog Content
` }) export class DialogExampleComponent implements OnInit { // Use @ViewChild to get a reference to the #dialog element @ViewChild('dialog') dialog?: ElementRef; ... constructor(...) { } ngOnInit() { } ... openDialog() { // Use nativeElement to access the mdui component this.dialog?.nativeElement.open = true; } } ``` # Integrate with Other Frameworks mdui is built with browser-native Web Components, making it compatible with all web frameworks. Here are ways to use mdui with popular frameworks. ## Aurelia {#Aurelia} After completing the [installation](/en/docs/2/getting-started/installation#npm) of mdui, you'll need to install and configure an additional package (Aurelia 2 only): ```bash npm install aurelia-mdui --save ``` and connect it to your application: ```typescript import { MduiWebTask } from 'aurelia-mdui'; Aurelia .register(MduiWebTask) .app(MyApp) .start(); ``` **Notes** Please send bug reports to [https://github.com/mreiche/aurelia-mdui](https://github.com/mreiche/aurelia-mdui) ## WebCell {#WebCell} To integrate mdui with [WebCell](https://web-cell.dev/), start by following the steps on the [installation](/en/docs/2/getting-started/installation#npm) page, first-class Web components, TypeScript & JSX supports is out of box. Or you can create a new project with [the official GitHub template repository](https://github.com/EasyWebApp/WebCell-mobile) by [clicking only one button](https://github.com/new?template_name=WebCell-mobile&template_owner=EasyWebApp). # Avatar Component Avatars represent users or entities by displaying images, icons, or characters. ## Usage {#usage} Import the component: ```js import 'mdui/components/avatar.js'; ``` Import the TypeScript type: ```ts import type { Avatar } from 'mdui/components/avatar.js'; ``` Example: ```html ``` ## Examples {#examples} ### Image Avatar {#example-src} To use an image as the avatar, specify the image link using the `src` attribute, or provide an `` element within the default slot. ```html Example of profile picture ``` The `fit` attribute determines how the image should fit the container box. It works similar to the native [`object-fit`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) property. ### Icon Avatar {#example-icon} To use a Material Icons icon as the avatar, specify the icon using the `icon` attribute. Alternatively, provide an icon element within the default slot. ```html ``` ### Character Avatar {#example-char} You can use any text within the default slot as the avatar. ```html A ``` ## mdui-avatar API ### Properties
Attribute Property Reflect Type Default Description
src src true string

URL of the avatar image.
fit fit true 'contain' | 'cover' | 'fill' | 'none' | 'scale-down'

Image resizing method, similar to the native CSS object-fit. Possible values:

  • contain: Scales the image to fit within the box while maintaining the aspect ratio. The image will be "letterboxed" if the aspect ratios do not match.
  • cover: Scales the image to fill the box while maintaining the aspect ratio. The image will be clipped if the aspect ratios do not match.
  • fill: Default. Scales the image to fill the box. The image will be stretched if the aspect ratios do not match.
  • none: No resizing.
  • scale-down: Scales as if none or contain were specified, choosing the smaller result.
icon icon true string

The Material Icons name for the avatar.
label label true string

Text description of the avatar.
### Slots
Name Description
(default)

Custom avatar content, such as letters, <img> elements, icons, etc.
### CSS Parts
Name Description
image

Internal <img> element when using an image avatar.
icon

Internal <mdui-icon> element when using an icon avatar.
### CSS Custom Properties
Name Description
--shape-corner

The size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.
# Badge Component Badges provide dynamic information, such as counts or status indications. They can contain labels or numbers. ## Usage {#usage} Import the component: ```js import 'mdui/components/badge.js'; ``` Import the TypeScript type: ```ts import type { Badge } from 'mdui/components/badge.js'; ``` example: ```html 12 ``` ## Examples {#examples} ### Variants {#example-variant} The `variant` attribute determines the badge's shape. A `large` value creates a larger badge. Specify the content to display within the default slot. ```html 99+ ``` ## mdui-badge API ### Properties
Attribute Property Reflect Type Default Description
variant variant true 'small' | 'large' 'large'

Defines the badge shape. Possible values:

  • small: A small badge without text.
  • large: A large badge with displayed text.
### Slots
Name Description
(default)

The text to be displayed.
### CSS Custom Properties
Name Description
--shape-corner

The size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.
# Bottom App Bar Component The Bottom App Bar provides navigation and key actions at the bottom of a mobile page. ## Usage {#usage} Import the component: ```js import 'mdui/components/bottom-app-bar.js'; ``` Import the TypeScript type: ```ts import type { BottomAppBar } from 'mdui/components/bottom-app-bar.js'; ``` Example: (Note: The `style="position: relative"` in the example is for demonstration purposes only. Remove it in actual use.) ```html
``` **Notes:** The BottomAppBar component uses `position: fixed` by default. It automatically adds `padding-bottom` to the `body` to prevent the page content from being obscured. However, it uses `position: absolute` in the following two cases: 1. When the `scroll-target` attribute is specified. In this case, `padding-bottom` will be added to the element specified by `scroll-target`. 2. When it's within the [``](/en/docs/2/components/layout) component. In this case, `padding-bottom` won't be added. ## Examples {#examples} ### In Container {#example-scroll-target} By default, the Bottom App Bar displays at the bottom of the page, relative to the current window. To place it inside a specific container, specify the `scroll-target` attribute with the CSS selector or DOM element of the container. Ensure the parent element has `position: relative; overflow: hidden` styles. ```html
Content
``` ### Hide on Scroll {#example-scroll-behavior} To hide the Bottom App Bar when scrolling down and display it when scrolling up, set the `scroll-behavior` attribute to `hide`. The `scroll-threshold` attribute can be used to set the number of pixels to start hiding the Bottom App Bar. ```html
Content
``` ### Fixed Floating Action Button {#example-fab-detach} If the Bottom App Bar includes a [Floating Action Button (FAB)](/en/docs/2/components/fab), add the `fab-detach` attribute to anchor the FAB at the page's bottom right when the Bottom App Bar hides on scroll. ```html
``` ## mdui-bottom-app-bar API ### Properties
Attribute Property Reflect Type Default Description
hide hide true boolean false

Hides the bottom app bar when set.
fab-detach fabDetach true boolean false

When set, detaches the <mdui-fab> from the bottom app bar. The <mdui-fab> remains on the page even after the app bar is hidden.
scroll-behavior scrollBehavior true 'hide' | 'shrink' | 'elevate'

Defines the scroll behavior. Possible values:

  • hide: Hides when scrolling.
scroll-target scrollTarget false string | HTMLElement | JQ<HTMLElement>

The element that listens for scroll events. Accepts a CSS selector, DOM element, or JQ object. Defaults to window.
scroll-threshold scrollThreshold true number

The scroll distance (in pixels) that triggers the scroll behavior.
order order true number

Specifies the layout order within the <mdui-layout> component. Items are sorted in ascending order. The default value is 0.
### Events
Name Description
show

Emitted when the bottom app bar starts to show. Can be prevented with event.preventDefault().
shown

Emitted after the bottom app bar has shown and animations are complete.
hide

Emitted when the bottom app bar starts to hide. Can be prevented with event.preventDefault().
hidden

Emitted after the bottom app bar has hidden and animations are complete.
### Slots
Name Description
(default)

Elements within the bottom app bar.
### CSS Custom Properties
Name Description
--shape-corner

The size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.
--z-index

The CSS z-index value of the component.
# Button Component Buttons are interactive components that enable users to execute actions such as sending emails, sharing documents, or expressing preferences. ## Usage {#usage} Import the component: ```js import 'mdui/components/button.js'; ``` Import the TypeScript type: ```ts import type { Button } from 'mdui/components/button.js'; ``` Example: ```html Button ``` ## Examples {#examples} ### Variant {#example-variant} The `variant` attribute determines the button's appearance. ```html Elevated Filled Tonal Outlined Text ``` ### Full Width {#example-full-width} Add the `full-width` attribute to make the button span the entire width of its container. ```html Button ``` ### Icons {#example-icon} Use the `icon` and `end-icon` attributes to add Material Icons to the left and right sides of the button, respectively. Alternatively, use the `icon` and `end-icon` slots to add custom elements to the button's sides. ```html Icon Slot ``` ### Link {#example-link} Use the `href` attribute to transform the button into a link. The `download`, `target`, and `rel` attributes are available for link-related functionality. ```html Link ``` ### Disabled and Loading States {#example-disabled} Use the `disabled` attribute to disable the button. The `loading` attribute displays a loading state. ```html Disabled Loading Loading & Disabled ``` ## mdui-button API ### Properties
Attribute Property Reflect Type Default Description
variant variant true 'elevated' | 'filled' | 'tonal' | 'outlined' | 'text' 'filled'

Defines the button style. Possible values:

  • elevated: A shadowed button for visual distinction.
  • filled: Used for final actions like 'Save' or 'Confirm'.
  • tonal: A mix between filled and outlined, suitable for medium to high-priority actions.
  • outlined: A bordered button for medium-priority and secondary actions.
  • text: A text button for low-priority actions.
full-width fullWidth true boolean false

If set, the button will fill the width of its parent element.
icon icon true string

Specifies the Material Icons name on the left. Alternatively, use slot="icon".
end-icon endIcon true string

Specifies the Material Icons name on the right. Alternatively, use slot="end-icon".
href href true string

The URL for the hyperlink. If provided, the component is rendered as an <a> element and can use link-related attributes.
download download true string

Instructs the browser to download the linked URL.

Note: This is only available when href is specified.
target target true '_blank' | '_parent' | '_self' | '_top'

Defines where to open the linked URL. Possible values:

  • _blank: Opens in a new tab or window.
  • _parent: Opens in the parent browsing context or _self if no parent.
  • _self: Opens in the current browsing context. (Default).
  • _top: Opens in the topmost browsing context or _self if no ancestors.

Note: This is only available when href is specified.
rel rel true 'alternate' | 'author' | 'bookmark' | 'external' | 'help' | 'license' | 'me' | 'next' | 'nofollow' | 'noreferrer' | 'opener' | 'prev' | 'search' | 'tag'

Specifies the relationship of the linked URL as space-separated link types. Possible values:

  • alternate: Alternate versions of the current document.
  • author: The author of the current document or article.
  • bookmark: The permalink for the nearest ancestor section.
  • external: The referenced document is not part of the same site as the current document.
  • help: A link to context-sensitive help.
  • license: Indicates that the main content of the current document is covered by the copyright license described by the referenced document.
  • me: Indicates that the current document represents the person who owns the linked content.
  • next: Indicates that the current document is part of a series and the next document in the series is the referenced document.
  • nofollow: Indicates that the current document's original author or publisher does not endorse the referenced document.
  • noreferrer: No Referer header will be included. Also has the same effect as noopener.
  • opener: Creates an auxiliary browsing context if the hyperlink would otherwise create a top-level browsing context that is not an auxiliary browsing context (i.e., has "_blank" as target attribute value).
  • prev: Indicates that the current document is part of a series and the previous document in the series is the referenced document.
  • search: Links to a resource that can be used to search through the current document and its related pages.
  • tag: Gives a tag (identified by the given address) that applies to the current document.

Note: This is only available when href is specified.
autofocus autofocus true boolean false

Specifies that the element should be focused when the page loads.
tabindex tabIndex false number

Defines the order in which the element receives focus when navigating with the Tab key.
disabled disabled true boolean false

Disables the element.
loading loading true boolean false

Indicates that the element is in a loading state.
name name true string ''

The button's name, which is submitted with form data.

Note: This is only available when href is not specified.
value value true string ''

The button's value, which is submitted with form data.

Note: This is only available when href is not specified.
type type true 'submit' | 'reset' | 'button' 'button'

Defines the button's default behavior. The default is button. Possible values:

  • submit: Submits the form data to the server.
  • reset: Resets all the controls to their initial values.
  • button: No default behavior, does nothing when pressed by default.

Note: This is only available when href is not specified.
form form true string

Associates the button with a <form> element. The value should be the id of a <form> in the same document. If not set, the button is associated with its parent <form>, if any.

This attribute allows button elements to be associated with <form>s anywhere in the document, not just inside a <form>.

Note: Only available when href is not specified.
formaction formAction true string

Specifies the URL that processes the button's submitted information. Overrides the action attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".
formenctype formEnctype true 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain'

Specifies the form data encoding method. Possible values:

  • application/x-www-form-urlencoded: Default if the attribute is not used.
  • multipart/form-data: Used for <input> elements with type set to file.
  • text/plain: For debugging, not for real form submission.

Overrides the enctype attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".
formmethod formMethod true 'post' | 'get'

Specifies the HTTP method for form submission. Possible values:

  • post: Form data included in HTTP request body.
  • get: Form data appended to action URL.

Overrides the method attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".
formnovalidate formNoValidate true boolean false

Specifies that the form should not be validated on submission. Overrides the novalidate attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".
formtarget formTarget true '_self' | '_blank' | '_parent' | '_top'

Specifies where to display the form submission response. Possible values:

  • _self: Current browsing context. (Default).
  • _blank: New tab or window.
  • _parent: Parent browsing context or _self if no parent.
  • _top: Topmost browsing context or _self if no ancestors.

Overrides the target attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".
undefined validity false ValidityState

A ValidityState object that represents the element's validity states.
undefined validationMessage false string

The element's validation message. This is empty if the element meets its constraints.
### Methods
Name Description
click(): void

Simulates a mouse click on the element.
focus(options?: FocusOptions): void

Sets focus on the element. An optional parameter can be an object with a preventScroll property. If preventScroll is set to true, the page will not scroll to bring the focused element into view.
blur(): void

Removes focus from the element.
checkValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event and returns false. If it's valid, it returns true.
reportValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event, returns false, and displays a validation message. If it's valid, it returns true.
setCustomValidity(message: string): void

Sets a custom error message. If the text is non-empty, it indicates that the field is invalid.
### Events
Name Description
focus

Emitted when the button gains focus.
blur

Emitted when the button loses focus.
invalid

Emitted when the form control's validity is checked and it doesn't meet the constraints.
### Slots
Name Description
(default)

Button text.
icon

Element on the left side of the button.
end-icon

Element on the right side of the button.
### CSS Parts
Name Description
button

Internal <button> or <a> element.
label

Button text.
icon

Icon on the left side of the button.
end-icon

Icon on the right side of the button.
loading

The <mdui-circular-progress> element for the loading state.
### CSS Custom Properties
Name Description
--shape-corner

The size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.
# Icon Button Component Icon buttons are used to execute minor actions with a single click. ## Usage {#usage} Import the component: ```js import 'mdui/components/button-icon.js'; ``` Import the TypeScript type: ```ts import type { ButtonIcon } from 'mdui/components/button-icon.js'; ``` Example: ```html ``` ## Examples {#examples} ### Icon {#example-icon} Use the `icon` attribute to specify the Material Icons name. Alternatively, you can use the default slot to specify the icon element. ```html ``` ### Shape {#example-variant} The `variant` attribute determines the shape of the icon button. ```html ``` ### Selectable {#example-selectable} Add the `selectable` attribute to make the icon button selectable. ```html ``` Use the `selected-icon` attribute to specify the Material Icons name for the selected state. Alternatively, use the `selected-icon` slot to specify the selected state icon element. ```html ``` The `selected` property is `true` when the icon button is selected. Add the `selected` attribute to set the icon button to the selected state by default. ```html ``` ### Link {#example-link} Use the `href` attribute to turn the icon button into a link. The `download`, `target`, and `rel` attributes are available for link-related functionality. ```html ``` ### Disabled and Loading State {#example-disabled} Use the `disabled` attribute to disable the icon button. The `loading` attribute displays the loading state. ```html ``` ## mdui-button-icon API ### Properties
Attribute Property Reflect Type Default Description
variant variant true 'standard' | 'filled' | 'tonal' | 'outlined' 'standard'

Defines the icon button style. Possible values:

  • standard: For low-priority actions.
  • filled: Has the strongest visual effect, suitable for high-priority actions.
  • tonal: A visual effect between filled and outlined, suitable for medium to high-priority actions.
  • outlined: For medium-priority actions.
icon icon true string

Specifies the Material Icons name. Alternatively, use the default slot.
selected-icon selectedIcon true string

Specifies the Material Icons name when selected. Alternatively, use slot="selected-icon".
selectable selectable true boolean false

Indicates if the button is selectable.
selected selected true boolean false

Indicates if the button is selected.
href href true string

The URL for the hyperlink. If provided, the component is rendered as an <a> element and can use link-related attributes.
download download true string

Instructs the browser to download the linked URL.

Note: This is only available when href is specified.
target target true '_blank' | '_parent' | '_self' | '_top'

Defines where to open the linked URL. Possible values:

  • _blank: Opens in a new tab or window.
  • _parent: Opens in the parent browsing context or _self if no parent.
  • _self: Opens in the current browsing context. (Default).
  • _top: Opens in the topmost browsing context or _self if no ancestors.

Note: This is only available when href is specified.
rel rel true 'alternate' | 'author' | 'bookmark' | 'external' | 'help' | 'license' | 'me' | 'next' | 'nofollow' | 'noreferrer' | 'opener' | 'prev' | 'search' | 'tag'

Specifies the relationship of the linked URL as space-separated link types. Possible values:

  • alternate: Alternate versions of the current document.
  • author: The author of the current document or article.
  • bookmark: The permalink for the nearest ancestor section.
  • external: The referenced document is not part of the same site as the current document.
  • help: A link to context-sensitive help.
  • license: Indicates that the main content of the current document is covered by the copyright license described by the referenced document.
  • me: Indicates that the current document represents the person who owns the linked content.
  • next: Indicates that the current document is part of a series and the next document in the series is the referenced document.
  • nofollow: Indicates that the current document's original author or publisher does not endorse the referenced document.
  • noreferrer: No Referer header will be included. Also has the same effect as noopener.
  • opener: Creates an auxiliary browsing context if the hyperlink would otherwise create a top-level browsing context that is not an auxiliary browsing context (i.e., has "_blank" as target attribute value).
  • prev: Indicates that the current document is part of a series and the previous document in the series is the referenced document.
  • search: Links to a resource that can be used to search through the current document and its related pages.
  • tag: Gives a tag (identified by the given address) that applies to the current document.

Note: This is only available when href is specified.
autofocus autofocus true boolean false

Specifies that the element should be focused when the page loads.
tabindex tabIndex false number

Defines the order in which the element receives focus when navigating with the Tab key.
disabled disabled true boolean false

Disables the element.
loading loading true boolean false

Indicates that the element is in a loading state.
name name true string ''

The button's name, which is submitted with form data.

Note: This is only available when href is not specified.
value value true string ''

The button's value, which is submitted with form data.

Note: This is only available when href is not specified.
type type true 'submit' | 'reset' | 'button' 'button'

Defines the button's default behavior. The default is button. Possible values:

  • submit: Submits the form data to the server.
  • reset: Resets all the controls to their initial values.
  • button: No default behavior, does nothing when pressed by default.

Note: This is only available when href is not specified.
form form true string

Associates the button with a <form> element. The value should be the id of a <form> in the same document. If not set, the button is associated with its parent <form>, if any.

This attribute allows button elements to be associated with <form>s anywhere in the document, not just inside a <form>.

Note: Only available when href is not specified.
formaction formAction true string

Specifies the URL that processes the button's submitted information. Overrides the action attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".
formenctype formEnctype true 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain'

Specifies the form data encoding method. Possible values:

  • application/x-www-form-urlencoded: Default if the attribute is not used.
  • multipart/form-data: Used for <input> elements with type set to file.
  • text/plain: For debugging, not for real form submission.

Overrides the enctype attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".
formmethod formMethod true 'post' | 'get'

Specifies the HTTP method for form submission. Possible values:

  • post: Form data included in HTTP request body.
  • get: Form data appended to action URL.

Overrides the method attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".
formnovalidate formNoValidate true boolean false

Specifies that the form should not be validated on submission. Overrides the novalidate attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".
formtarget formTarget true '_self' | '_blank' | '_parent' | '_top'

Specifies where to display the form submission response. Possible values:

  • _self: Current browsing context. (Default).
  • _blank: New tab or window.
  • _parent: Parent browsing context or _self if no parent.
  • _top: Topmost browsing context or _self if no ancestors.

Overrides the target attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".
undefined validity false ValidityState

A ValidityState object that represents the element's validity states.
undefined validationMessage false string

The element's validation message. This is empty if the element meets its constraints.
### Methods
Name Description
click(): void

Simulates a mouse click on the element.
focus(options?: FocusOptions): void

Sets focus on the element. An optional parameter can be an object with a preventScroll property. If preventScroll is set to true, the page will not scroll to bring the focused element into view.
blur(): void

Removes focus from the element.
checkValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event and returns false. If it's valid, it returns true.
reportValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event, returns false, and displays a validation message. If it's valid, it returns true.
setCustomValidity(message: string): void

Sets a custom error message. If the text is non-empty, it indicates that the field is invalid.
### Events
Name Description
focus

Emitted when the button gains focus.
blur

Emitted when the button loses focus.
change

Emitted when the selected state changes.
invalid

Emitted when the form control's validity is checked and it doesn't meet the constraints.
### Slots
Name Description
(default)

Icon component.
selected-icon

Icon in the selected state.
### CSS Parts
Name Description
button

Internal <button> or <a> element.
icon

Icon.
selected-icon

Icon in the selected state.
loading

The <mdui-circular-progress> element for the loading state.
### CSS Custom Properties
Name Description
--shape-corner

The size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.
# Card Component Cards are versatile components that serve as containers for content and actions about a single subject. ## Usage {#usage} Import the component: ```js import 'mdui/components/card.js'; ``` Import the TypeScript type: ```ts import type { Card } from 'mdui/components/card.js'; ``` Example: ```html Card ``` ## Examples {#examples} ### Variant {#example-variant} The `variant` attribute determines the card's appearance. ```html ``` ### Clickable {#example-clickable} Add the `clickable` attribute to make the card interactive. This will add hover and click ripple effects. ```html ``` ### Link {#example-link} Use the `href` attribute to transform the card into a link. The `download`, `target`, and `rel` attributes are available for link-related functionality. ```html ``` ### Disabled State {#example-disabled} Use the `disabled` attribute to disable the card. ```html ``` ## mdui-card API ### Properties
Attribute Property Reflect Type Default Description
variant variant true 'elevated' | 'filled' | 'outlined' 'elevated'

Defines the card style. Possible values:

  • elevated: Shadowed, providing more visual separation from the background than filled, but less than outlined.
  • filled: Provides minimal visual separation from the background.
  • outlined: Bordered, providing maximum visual separation from the background.
clickable clickable true boolean false

Makes the card clickable. When set, a mouse hover effect and click ripple effect are added.
disabled disabled true boolean false

Disables the card.
href href true string

The URL for the hyperlink. If specified, the component renders as an <a> element and can use link-related attributes.
download download true string

Instructs the browser to treat the linked URL as a download.

Note: This is only available when href is specified.
target target true '_blank' | '_parent' | '_self' | '_top'

Defines where to display the linked URL. Possible values:

  • _blank: Opens in a new tab or window.
  • _parent: Opens in the parent browsing context or _self if no parent exists.
  • _self: Opens in the current browsing context. (Default).
  • _top: Opens in the topmost browsing context or _self if no ancestors exist.

Note: This is only available when href is specified.
rel rel true 'alternate' | 'author' | 'bookmark' | 'external' | 'help' | 'license' | 'me' | 'next' | 'nofollow' | 'noreferrer' | 'opener' | 'prev' | 'search' | 'tag'

Specifies the relationship of the linked URL as space-separated link types. Possible values:

  • alternate: Alternate versions of the current document.
  • author: Author of the current document or article.
  • bookmark: Permanent link for the nearest ancestor section.
  • external: The referenced document is not part of the same site as the current document.
  • help: Link to context-sensitive help.
  • license: Indicates that the main content of the current document is covered by the copyright license described by the referenced document.
  • me: Indicates that the current document represents the person who owns the linked content.
  • next: Indicates that the current document is part of a series and the next document in the series is the referenced document.
  • nofollow: Indicates that the current document's original author or publisher does not endorse the referenced document.
  • noreferrer: No Referer header will be included. Also has the same effect as noopener.
  • opener: Creates an auxiliary browsing context if the hyperlink would otherwise create a top-level browsing context that is not an auxiliary browsing context (i.e., has "_blank" as target attribute value).
  • prev: Indicates that the current document is part of a series and the previous document in the series is the referenced document.
  • search: Links to a resource that can be used to search through the current document and its related pages.
  • tag: Gives a tag (identified by the given address) that applies to the current document.

Note: This is only available when href is specified.
autofocus autofocus true boolean false

Determines if the element should be focused when the page loads.
tabindex tabIndex false number

Specifies the order in which the element receives focus when navigating with the Tab key.
### Methods
Name Description
click(): void

Simulates a mouse click on the element.
focus(options?: FocusOptions): void

Sets focus on the element. An optional parameter can be an object with a preventScroll property. If preventScroll is set to true, the page will not scroll to bring the focused element into view.
blur(): void

Removes focus from the element.
### Events
Name Description
focus

Emitted when the card gains focus.
blur

Emitted when the card loses focus.
### Slots
Name Description
(default)

Card content.
### CSS Custom Properties
Name Description
--shape-corner

The size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.
# Checkbox Component Checkboxes allow users to select one or more options from a set. Each checkbox can toggle between checked and unchecked states. ## Usage {#usage} Import the component: ```js import 'mdui/components/checkbox.js'; ``` Import the TypeScript type: ```ts import type { Checkbox } from 'mdui/components/checkbox.js'; ``` Example: ```html Checkbox ``` ## Examples {#examples} ### Checked State {#example-checked} The `checked` property is `true` when the checkbox is checked. Add the `checked` attribute to set the checkbox to the checked state by default. ```html Checkbox ``` ### Disabled State {#example-disabled} Use the `disabled` attribute to disable the checkbox. ```html Checkbox Checkbox ``` ### Indeterminate State {#example-indeterminate} The `indeterminate` attribute indicates an indeterminate state for the checkbox. ```html Checkbox ``` ### Icons {#example-icon} Use the `unchecked-icon`, `checked-icon`, and `indeterminate-icon` attributes to set Material Icons for the checkbox in unchecked, checked, and indeterminate states, respectively. Alternatively, use the corresponding slots for setting icons. ```html Checkbox Checkbox
Checkbox Checkbox ``` ## mdui-checkbox API ### Properties
Attribute Property Reflect Type Default Description
disabled disabled true boolean false

Dsiables the checkbox.
checked checked true boolean false

Sets the checkbox to the checked state.
undefined defaultChecked false boolean false

Sets the default checked state. Resets to this state when the form is reset. Can only be set via JavaScript property.
indeterminate indeterminate true boolean false

Sets the checkbox to an indeterminate state.
required required true boolean false

Requires the checkbox to be checked for form submission.
form form true string

Associates the checkbox with a <form> element. The value should be the id of a <form> in the same document. If not set, the checkbox is associated with its parent <form>, if any.

This attribute allows checkbox elements to be associated with <form>s anywhere in the document, not just inside a <form>.
name name true string ''

Sets the checkbox's name, which is submitted with form data.
value value true string 'on'

Sets the checkbox's value, which is submitted with form data.
unchecked-icon uncheckedIcon true string

Sets the Material Icons name for the unchecked state. Alternatively, use slot="unchecked-icon".
checked-icon checkedIcon true string

Sets the Material Icons name for the checked state. Alternatively, use slot="checked-icon".
indeterminate-icon indeterminateIcon true string

Sets the Material Icons name for the indeterminate state. Alternatively, use slot="indeterminate-icon".
undefined validity false ValidityState

A ValidityState object that represents the element's validity states.
undefined validationMessage false string

The element's validation message. This is empty if the element meets its constraints.
autofocus autofocus true boolean false

Determines if the element should be focused when the page loads.
tabindex tabIndex false number

Specifies the order in which the element receives focus when navigating with the Tab key.
### Methods
Name Description
checkValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event and returns false. If it's valid, it returns true.
reportValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event, returns false, and displays a validation message. If it's valid, it returns true.
setCustomValidity(message: string): void

Sets a custom error message. If the text is non-empty, it indicates that the field is invalid.
click(): void

Simulates a mouse click on the element.
focus(options?: FocusOptions): void

Sets focus on the element. An optional parameter can be an object with a preventScroll property. If preventScroll is set to true, the page will not scroll to bring the focused element into view.
blur(): void

Removes focus from the element.
### Events
Name Description
focus

Emitted when the checkbox gains focus.
blur

Emitted when the checkbox loses focus.
change

Emitted when the checked state changes.
input

Emitted when the checked state changes.
invalid

Emitted when the form control's validity is checked and it doesn't meet the constraints.
### Slots
Name Description
(default)

Text.
unchecked-icon

Icon for the unchecked state.
checked-icon

Icon for the checked state.
indeterminate-icon

Icon for the indeterminate state.
### CSS Parts
Name Description
control

Container for the left icon.
unchecked-icon

Icon for the unchecked state.
checked-icon

Icon for the checked state.
indeterminate-icon

Icon for the indeterminate state.
label

Text.
# Chip Component Chips are compact elements that represent an input, attribute, or action. ## Usage {#usage} Import the component: ```js import 'mdui/components/chip.js'; ``` Import the TypeScript type: ```ts import type { Chip } from 'mdui/components/chip.js'; ``` Example: ```html Chip ``` ## Examples {#examples} ### Variant {#example-variant} The `variant` attribute determines the chip's appearance. There are four available variants: * `assist`: Represents smart or automated actions that can span multiple apps. * `filter`: Represents filters for a collection. * `input`: Represents discrete pieces of information entered by a user. * `suggestion`: Helps narrow a user’s intent by presenting dynamically generated suggestions. ```html Assist Filter Input Suggestion ``` ### Elevated {#example-elevated} Add the `elevated` attribute to raise the chip, providing it with a shadow. ```html Chip ``` ### Icons {#example-icon} Use the `icon` and `end-icon` attributes to add Material Icons to the left and right sides of the chip, respectively. Alternatively, use the `icon` and `end-icon` slots to add elements to the chip's sides. ```html Icon End Icon Slot ``` ### Link {#example-link} Use the `href` attribute to transform the chip into a link. The `download`, `target`, and `rel` attributes are available for link-related functionality. ```html Link ``` ### Disabled and Loading States {#example-disabled} Use the `disabled` attribute to disable the chip. The `loading` attribute displays the loading state. ```html Disabled Loading Loading & Disabled ``` ### Selectable {#example-selectable} Add the `selectable` attribute to make the chip selectable. ```html Chip ``` Use the `selected-icon` attribute to specify the Material Icons name for the selected state. Alternatively, use the `selected-icon` slot to specify the selected state icon element. ```html Chip Chip ``` The `selected` property is `true` when the chip is selected. Add the `selected` attribute to set the chip as selected by default. ```html Chip ``` ### Deletable {#example-deletable} Add the `deletable` attribute to add a delete icon to the right of the chip. Clicking this icon triggers the `delete` event. Use the `delete-icon` attribute to specify the Material Icons for the delete icon, or use the `delete-icon` slot to specify the element for the delete icon. ```html Chip Chip Chip ``` ## mdui-chip API ### Properties
Attribute Property Reflect Type Default Description
variant variant true 'assist' | 'filter' | 'input' | 'suggestion' 'assist'

Defines the chip type. Possible values:

  • assist: Displays auxiliary actions related to the context, such as sharing and favoriting on a meal ordering page.
  • filter: Filters content, like search results on a search results page.
  • input: Represents fragments of user input, such as contacts in the 'To' field in Gmail.
  • suggestion: Provides dynamically generated suggestions to simplify user actions, like message predictions in a chat application.
elevated elevated true boolean false

Gives the chip a shadow.
selectable selectable true boolean false

Makes the chip selectable.
selected selected true boolean false

Marks the chip as selected.
deletable deletable true boolean false

Makes the chip deletable. When set, a delete icon appears on the right.
icon icon true string

Sets the Material Icons name for the left icon. Alternatively, use slot="icon".
selected-icon selectedIcon true string

Sets the Material Icons name for the left icon when selected. Alternatively, use slot="selected-icon".
end-icon endIcon true string

Sets the Material Icons name for the right icon. Alternatively, use slot="end-icon".
delete-icon deleteIcon true string

Sets the Material Icons name for the delete icon when deletable. Alternatively, use slot="delete-icon".
href href true string

The URL for the hyperlink. If provided, the component is rendered as an <a> element and can use link-related attributes.
download download true string

Instructs the browser to download the linked URL.

Note: This is only available when href is specified.
target target true '_blank' | '_parent' | '_self' | '_top'

Defines where to open the linked URL. Possible values:

  • _blank: Opens in a new tab or window.
  • _parent: Opens in the parent browsing context or _self if no parent.
  • _self: Opens in the current browsing context. (Default).
  • _top: Opens in the topmost browsing context or _self if no ancestors.

Note: This is only available when href is specified.
rel rel true 'alternate' | 'author' | 'bookmark' | 'external' | 'help' | 'license' | 'me' | 'next' | 'nofollow' | 'noreferrer' | 'opener' | 'prev' | 'search' | 'tag'

Specifies the relationship of the linked URL as space-separated link types. Possible values:

  • alternate: Alternate versions of the current document.
  • author: The author of the current document or article.
  • bookmark: The permalink for the nearest ancestor section.
  • external: The referenced document is not part of the same site as the current document.
  • help: A link to context-sensitive help.
  • license: Indicates that the main content of the current document is covered by the copyright license described by the referenced document.
  • me: Indicates that the current document represents the person who owns the linked content.
  • next: Indicates that the current document is part of a series and the next document in the series is the referenced document.
  • nofollow: Indicates that the current document's original author or publisher does not endorse the referenced document.
  • noreferrer: No Referer header will be included. Also has the same effect as noopener.
  • opener: Creates an auxiliary browsing context if the hyperlink would otherwise create a top-level browsing context that is not an auxiliary browsing context (i.e., has "_blank" as target attribute value).
  • prev: Indicates that the current document is part of a series and the previous document in the series is the referenced document.
  • search: Links to a resource that can be used to search through the current document and its related pages.
  • tag: Gives a tag (identified by the given address) that applies to the current document.

Note: This is only available when href is specified.
autofocus autofocus true boolean false

Specifies that the element should be focused when the page loads.
tabindex tabIndex false number

Defines the order in which the element receives focus when navigating with the Tab key.
disabled disabled true boolean false

Disables the element.
loading loading true boolean false

Indicates that the element is in a loading state.
name name true string ''

The button's name, which is submitted with form data.

Note: This is only available when href is not specified.
value value true string ''

The button's value, which is submitted with form data.

Note: This is only available when href is not specified.
type type true 'submit' | 'reset' | 'button' 'button'

Defines the button's default behavior. The default is button. Possible values:

  • submit: Submits the form data to the server.
  • reset: Resets all the controls to their initial values.
  • button: No default behavior, does nothing when pressed by default.

Note: This is only available when href is not specified.
form form true string

Associates the button with a <form> element. The value should be the id of a <form> in the same document. If not set, the button is associated with its parent <form>, if any.

This attribute allows button elements to be associated with <form>s anywhere in the document, not just inside a <form>.

Note: Only available when href is not specified.
formaction formAction true string

Specifies the URL that processes the button's submitted information. Overrides the action attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".
formenctype formEnctype true 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain'

Specifies the form data encoding method. Possible values:

  • application/x-www-form-urlencoded: Default if the attribute is not used.
  • multipart/form-data: Used for <input> elements with type set to file.
  • text/plain: For debugging, not for real form submission.

Overrides the enctype attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".
formmethod formMethod true 'post' | 'get'

Specifies the HTTP method for form submission. Possible values:

  • post: Form data included in HTTP request body.
  • get: Form data appended to action URL.

Overrides the method attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".
formnovalidate formNoValidate true boolean false

Specifies that the form should not be validated on submission. Overrides the novalidate attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".
formtarget formTarget true '_self' | '_blank' | '_parent' | '_top'

Specifies where to display the form submission response. Possible values:

  • _self: Current browsing context. (Default).
  • _blank: New tab or window.
  • _parent: Parent browsing context or _self if no parent.
  • _top: Topmost browsing context or _self if no ancestors.

Overrides the target attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".
undefined validity false ValidityState

A ValidityState object that represents the element's validity states.
undefined validationMessage false string

The element's validation message. This is empty if the element meets its constraints.
### Methods
Name Description
click(): void

Simulates a mouse click on the element.
focus(options?: FocusOptions): void

Sets focus on the element. An optional parameter can be an object with a preventScroll property. If preventScroll is set to true, the page will not scroll to bring the focused element into view.
blur(): void

Removes focus from the element.
checkValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event and returns false. If it's valid, it returns true.
reportValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event, returns false, and displays a validation message. If it's valid, it returns true.
setCustomValidity(message: string): void

Sets a custom error message. If the text is non-empty, it indicates that the field is invalid.
### Events
Name Description
focus

Emitted when the chip gains focus.
blur

Emitted when the chip loses focus.
invalid

Emitted when the form control's validity is checked and it doesn't meet the constraints.
change

Emitted when the selected state changes.
delete

Emitted when the delete icon is clicked.
### Slots
Name Description
(default)

Text.
icon

Left icon.
end-icon

Right icon.
selected-icon

Left icon when selected.
delete-icon

Delete icon when deletable.
### CSS Parts
Name Description
button

Internal <button> or <a> element.
label

Text.
icon

Left icon.
end-icon

Right icon.
selected-icon

Left icon when selected.
delete-icon

Delete icon on the right.
loading

The <mdui-circular-progress> element for the loading state.
### CSS Custom Properties
Name Description
--shape-corner

The size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.
# Circular Progress Component Circular progress indicators are used to show the progress of ongoing tasks. ## Usage {#usage} Import the component: ```js import 'mdui/components/circular-progress.js'; ``` Import the TypeScript type: ```ts import type { CircularProgress } from 'mdui/components/circular-progress.js'; ``` Example: ```html ``` ## Examples {#examples} ### Determinate Progress {#example-value} By default, the circular progress indicator is in an indeterminate state. To set the current progress, use the `value` attribute. The default maximum progress value is `1`. ```html ``` To set the maximum progress value, use the `max` attribute. ```html ``` ## mdui-circular-progress API ### Properties
Attribute Property Reflect Type Default Description
max max true number 1

Sets the maximum value for the progress indicator. The default value is 1.
value value false number

Sets the current value of the progress indicator. If not specified, the progress indicator is in an indeterminate state.
# Collapse Component Collapse panels are utilized to group and conceal complex content areas, enhancing page organization. The collapse panel component does not come with styles. You must either create your own styles or use it in conjunction with other components. ## Usage {#usage} Import the component: ```js import 'mdui/components/collapse.js'; import 'mdui/components/collapse-item.js'; ``` Import the TypeScript type: ```ts import type { Collapse } from 'mdui/components/collapse.js'; import type { CollapseItem } from 'mdui/components/collapse-item.js'; ``` Example: ```html first content second content ``` ## Examples {#examples} ### Panel Header and Content {#example-header} You can set the panel header text using the `header` attribute of the `` component. Alternatively, use the `header` slot to specify the panel header element. The default slot of the component is for the panel content. ```html Item 1
Item 1 - subitem
Item 2
Item 2 - subitem
``` ### Accordion Mode {#example-accordion} To enable accordion mode, add the `accordion` attribute to the `` component. In this mode, only one panel can be open at a time. ```html Item 1
Item 1 - subitem
Item 2
Item 2 - subitem
``` ### Setting the Active Panel {#example-value} The `value` attribute of the `` component can be used to get the currently open panel or set the panel you want to open. In accordion mode, `value` is a string and can be manipulated using either attribute or property. In non-accordion mode, `value` is an array and can only be manipulated using JavaScript property. ```html Accordion Mode Item 1
Item 1 - subitem
Item 2
Item 2 - subitem
Non-Accordion Mode Item 1
Item 1 - subitem
Item 2
Item 2 - subitem
``` ### Disabled State {#example-disabled} To disable the entire collapse panel group, add the `disabled` attribute to the `` component. To disable a specific collapse panel, add the `disabled` attribute to the ``. ```html All Disabled Item 1
Item 1 - subitem
Item 2
Item 2 - subitem
Disable the First Panel Item 1
Item 1 - subitem
Item 2
Item 2 - subitem
``` ### Triggering Element for Collapse {#example-trigger} By default, clicking the entire panel header area triggers the collapse. You can specify the triggering element by using the `trigger` attribute of the `` component. The `trigger` attribute can be a CSS selector or a DOM element. ```html Item 1
Item 1 - subitem
``` ## mdui-collapse-item API ### Properties
Attribute Property Reflect Type Default Description
value value true string

Specifies the value of the collapsible panel item.
header header true string

Sets the header text for the collapsible panel item.
disabled disabled true boolean false

Disables the collapsible panel item.
trigger trigger false string | HTMLElement | JQ<HTMLElement>

Identifies the element that triggers the collapse on click. This can be a CSS selector, a DOM element, or a JQ object. By default, the entire header area is the trigger.
### Events
Name Description
open

Emitted when the collapse item starts to open.
opened

Emitted after the collapse item has opened and the animations are completed.
close

Emitted when the collapse item starts to close.
closed

Emitted after the collapse item has closed and the animations are completed.
### Slots
Name Description
(default)

Main content of the collapsible panel item.
header

Content of the collapsible panel item's header.
### CSS Parts
Name Description
header

Content of the collapsible panel's header.
body

Content of the collapsible panel's body.
## mdui-collapse API ### Properties
Attribute Property Reflect Type Default Description
accordion accordion true boolean false

Activates accordion mode.
value value false string | string[]

Specifies the open <mdui-collapse-item> value.

Note: The HTML attribute is always a string and can only be initially set when accordion is true. The JavaScript property value is a string when accordion is true and a string array when accordion is false. To modify this value when accordion is false, you must change the JavaScript property.
disabled disabled true boolean false

Disables the collapsible panel.
### Events
Name Description
change

Emitted when the open collapsible panel item changes.
### Slots
Name Description
(default)

The <mdui-collapse-item> components.
# Dialog Component Dialogs are used to display crucial information during a user's workflow. In addition to directly using this component, mdui also provides four functions: [`mdui.dialog`](/en/docs/2/functions/dialog), [`mdui.alert`](/en/docs/2/functions/alert), [`mdui.confirm`](/en/docs/2/functions/confirm), [`mdui.prompt`](/en/docs/2/functions/prompt). These functions simplify the use of the Dialog component. ## Usage {#usage} Import the component: ```js import 'mdui/components/dialog.js'; ``` Import the TypeScript type: ```ts import type { Dialog } from 'mdui/components/dialog.js'; ``` Example: ```html Dialog Close Open Dialog ``` ## Examples {#examples} ### Close on Overlay Click {#example-close-on-overlay-click} Add the `close-on-overlay-click` attribute to close the dialog when the overlay is clicked. ```html Dialog Open Dialog ``` ### Close on ESC {#example-close-on-esc} Add the `close-on-esc` attribute to enable closing the dialog when the ESC key is pressed. ```html Dialog Open Dialog ``` ### Fullscreen {#example-fullscreen} Add the `fullscreen` attribute to make the dialog fullscreen. ```html Dialog Close Open Dialog ``` ### Icon {#example-icon} Set the `icon` attribute to add a Material Icon above the dialog. ```html Dialog Open Dialog ``` Alternatively, add an icon element above the dialog using the `icon` slot. ```html Dialog Open Dialog ``` ### Title and Description {#example-headline} Use the `headline` and `description` attributes to set the dialog's title and description. ```html Open Dialog ``` Alternatively, use the `headline` and `description` slots to set the title and description elements. ```html Delete selected images? Images will be permenantly removed from you account and all synced devices. Open Dialog ``` ### Action Buttons at the Bottom {#example-action} Use the `action` slot to add action buttons at the bottom of the dialog. ```html Cancel Delete Open Dialog ``` Add the `stacked-actions` attribute to stack the action buttons vertically. ```html Turn on speed boost No thanks Open Dialog ``` ### Top Content {#example-header} Use the `header` slot to set the top content of the dialog. ```html Title Save
Open Dialog ``` ## mdui-dialog API ### Properties
Attribute Property Reflect Type Default Description
icon icon true string

Sets the Material Icons name for the top icon. Alternatively, use slot="icon".
headline headline true string

Sets the dialog title. Alternatively, use slot="headline".
description description true string

Sets the text below the title. Alternatively, use slot="description".
open open true boolean false

Opens the dialog.
fullscreen fullscreen true boolean false

Sets the dialog to full-screen.
close-on-esc closeOnEsc true boolean false

Closes the dialog when the ESC key is pressed.
close-on-overlay-click closeOnOverlayClick true boolean false

Closes the dialog when the overlay is clicked.
stacked-actions stackedActions true boolean false

Stacks the bottom action buttons vertically.
### Events
Name Description
open

Emitted when the dialog starts to open. Can be prevented with event.preventDefault().
opened

Emitted after the dialog has opened and the animations are completed.
close

Emitted when the dialog starts to close. Can be prevented with event.preventDefault()..
closed

Emitted after the dialog has closed and the animations are completed.
overlay-click

Emitted when the overlay is clicked.
### Slots
Name Description
header

Top element, contains the icon slot and headline slot by default.
icon

Top icon.
headline

Top headline.
description

Text below the title.
(default)

Main content of the dialog.
action

Elements in the bottom action bar.
### CSS Parts
Name Description
overlay

Overlay layer.
panel

Dialog container.
header

Dialog header, includes icon and headline.
icon

Top icon in header.
headline

Top headline in header.
body

Dialog body.
description

Subtext in body.
action

Bottom action buttons.
### CSS Custom Properties
Name Description
--shape-corner

The size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.
--z-index

The CSS z-index value of the component.
# Divider Component A divider is a thin line that groups content in lists and layouts. ## Usage {#usage} Import the component: ```js import 'mdui/components/divider.js'; ``` Import the TypeScript type: ```ts import type { Divider } from 'mdui/components/divider.js'; ``` Example: ```html ``` ## Examples {#examples} ### Vertical Divider {#example-vertical} To display the divider vertically, add the `vertical` attribute. ```html
``` ### Left Inset {#example-inset} To inset the divider from the left, add the `inset` attribute. This is typically used in lists to align the divider with the text on the left. ```html Item 1 Item 2 ``` ### Middle Inset {#example-middle} To inset the divider from both sides, add the `middle` attribute. ```html Item 1 Item 2 ``` ## mdui-divider API ### Properties
Attribute Property Reflect Type Default Description
vertical vertical true boolean false

Displays the divider vertically.
inset inset true boolean false

Adds an inset from the left side.
middle middle true boolean false

Adds insets from both the left and right sides.
# Dropdown Component The Dropdown component displays specific content in a pop-up control. It is often used in conjunction with the Menu component. ## Usage {#usage} Import the component: ```js import 'mdui/components/dropdown.js'; ``` Import the TypeScript type: ```ts import type { Dropdown } from 'mdui/components/dropdown.js'; ``` Example: ```html open dropdown Item 1 Item 2 ``` ## Examples {#examples} ### Disabled State {#example-disabled} Add the `disabled` attribute to disable the dropdown. ```html open dropdown Item 1 Item 2 ``` ### Open Position {#example-placement} Set the `placement` attribute to control the dropdown's open position. ```html open dropdown Item 1 Item 2 ``` ### Trigger Method {#example-trigger} Set the dropdown's trigger method with the `trigger` attribute. ```html open dropdown Item 1 Item 2 ``` ### Open on Pointer {#example-open-on-pointer} Add the `open-on-pointer` attribute to open the dropdown at the pointer location. This is often combined with `trigger="contextmenu"` for right-click menu activation. ```html Open the menu here with the right mouse button Item 1 Item 2 ``` ### Keep Menu Open {#example-stay-open-on-click} By default, clicking a menu item in the dropdown component closes it. Add `stay-open-on-click` to keep it open. ```html open dropdown Item 1 Item 2 ``` ### Open/Close Delay {#example-delay} With `trigger="hover"`, use `open-delay` and `close-delay` to set the open and close delays. ```html open dropdown Item 1 Item 2 ``` ## mdui-dropdown API ### Properties
Attribute Property Reflect Type Default Description
open open true boolean false

Opens the dropdown.
disabled disabled true boolean false

Disables the dropdown.
trigger trigger true 'click' | 'hover' | 'focus' | 'contextmenu' | 'manual' | string 'click'

Defines the trigger method for the dropdown. Supports multiple space-separated values. Possible values:

  • click: Trigger on click.
  • hover: Trigger on mouse hover.
  • focus: Trigger on focus.
  • contextmenu: Trigger on right-click or touch long press.
  • manual: If used, the dropdown can only be opened and closed programmatically, and no other trigger methods can be specified.
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'

Sets the position of the dropdown. Possible values:

  • auto: Automatically determine the position.
  • top-start: Above and left-aligned.
  • top: Above and centered.
  • top-end: Above and right-aligned.
  • bottom-start: Below and left-aligned.
  • bottom: Below and centered.
  • bottom-end: Below and right-aligned.
  • left-start: Left and top-aligned.
  • left: Left and centered.
  • left-end: Left and bottom-aligned.
  • right-start: Right and top-aligned.
  • right: Right and centered.
  • right-end: Right and bottom-aligned.
stay-open-on-click stayOpenOnClick true boolean false

Keeps the dropdown open after clicking an <mdui-menu-item>.
open-delay openDelay true number 150

Sets the delay (in ms) for opening the dropdown on hover.
close-delay closeDelay true number 150

Sets the delay (in ms) for closing the dropdown on hover.
open-on-pointer openOnPointer true boolean false

Opens the dropdown at the cursor position. This is typically used for context menus.
### Events
Name Description
open

Emitted when the dropdown starts to open. Can be prevented with event.preventDefault().
opened

Emitted after the dropdown has opened and the animations are completed.
close

Emitted when the dropdown starts to close. Can be prevented with event.preventDefault().
closed

Emitted after the dropdown has closed and the animations are completed.
### Slots
Name Description
(default)

The content of the dropdown.
trigger

The element that triggers the dropdown, such as an <mdui-button> element.
### CSS Parts
Name Description
trigger

The container of the element that triggers the dropdown, i.e., the container of the trigger slot.
panel

The container of the dropdown content.
### CSS Custom Properties
Name Description
--z-index

The CSS z-index value of the component.
# Fab Component The Floating Action Button (FAB) is a primary component for key actions, offering easy access. ## Usage {#usage} Import the component: ```js import 'mdui/components/fab.js'; ``` Import the TypeScript type: ```ts import type { Fab } from 'mdui/components/fab.js'; ``` Example: ```html ``` ## Examples {#examples} ### Icon {#example-icon} Set the Material Icon name with the `icon` attribute or use the `icon` slot. ```html ``` ### Extended State {#example-extended} Use `extended` to display text from the default slot in the extended state. ```html Compose ``` ### Shape {#example-variant} Set the FAB shape with the `variant` attribute. ```html ``` ### Size {#example-size} Set the FAB size with the `size` attribute. ```html ``` ### Link {#example-link} Use the `href` attribute to turn the FAB into a link. The `download`, `target`, and `rel` attributes are available for link-related functionality. ```html ``` ### Disabled and Loading State {#example-disabled} Use `disabled` to disable the FAB. Use `loading` to add a loading state. ```html ``` ## mdui-fab API ### Properties
Attribute Property Reflect Type Default Description
variant variant true 'primary' | 'surface' | 'secondary' | 'tertiary' 'primary'

Sets the FAB color. Possible values:

  • primary: Uses the primary container background color.
  • surface: Uses the surface container high background color.
  • secondary: Uses the secondary container background color.
  • tertiary: Uses the tertiary container background color.
size size true 'normal' | 'small' | 'large' 'normal'

Sets the FAB size. Possible values:

  • normal: Sets the FAB to a normal size.
  • small: Sets the FAB to a small size.
  • large: Sets the FAB to a large size.
icon icon true string

Sets the Material Icons name. Alternatively, use slot="icon".
extended extended true boolean false

Indicates if the FAB is in the extended state.
href href true string

The URL for the hyperlink. If provided, the component is rendered as an <a> element and can use link-related attributes.
download download true string

Instructs the browser to download the linked URL.

Note: This is only available when href is specified.
target target true '_blank' | '_parent' | '_self' | '_top'

Defines where to open the linked URL. Possible values:

  • _blank: Opens in a new tab or window.
  • _parent: Opens in the parent browsing context or _self if no parent.
  • _self: Opens in the current browsing context. (Default).
  • _top: Opens in the topmost browsing context or _self if no ancestors.

Note: This is only available when href is specified.
rel rel true 'alternate' | 'author' | 'bookmark' | 'external' | 'help' | 'license' | 'me' | 'next' | 'nofollow' | 'noreferrer' | 'opener' | 'prev' | 'search' | 'tag'

Specifies the relationship of the linked URL as space-separated link types. Possible values:

  • alternate: Alternate versions of the current document.
  • author: The author of the current document or article.
  • bookmark: The permalink for the nearest ancestor section.
  • external: The referenced document is not part of the same site as the current document.
  • help: A link to context-sensitive help.
  • license: Indicates that the main content of the current document is covered by the copyright license described by the referenced document.
  • me: Indicates that the current document represents the person who owns the linked content.
  • next: Indicates that the current document is part of a series and the next document in the series is the referenced document.
  • nofollow: Indicates that the current document's original author or publisher does not endorse the referenced document.
  • noreferrer: No Referer header will be included. Also has the same effect as noopener.
  • opener: Creates an auxiliary browsing context if the hyperlink would otherwise create a top-level browsing context that is not an auxiliary browsing context (i.e., has "_blank" as target attribute value).
  • prev: Indicates that the current document is part of a series and the previous document in the series is the referenced document.
  • search: Links to a resource that can be used to search through the current document and its related pages.
  • tag: Gives a tag (identified by the given address) that applies to the current document.

Note: This is only available when href is specified.
autofocus autofocus true boolean false

Specifies that the element should be focused when the page loads.
tabindex tabIndex false number

Defines the order in which the element receives focus when navigating with the Tab key.
disabled disabled true boolean false

Disables the element.
loading loading true boolean false

Indicates that the element is in a loading state.
name name true string ''

The button's name, which is submitted with form data.

Note: This is only available when href is not specified.
value value true string ''

The button's value, which is submitted with form data.

Note: This is only available when href is not specified.
type type true 'submit' | 'reset' | 'button' 'button'

Defines the button's default behavior. The default is button. Possible values:

  • submit: Submits the form data to the server.
  • reset: Resets all the controls to their initial values.
  • button: No default behavior, does nothing when pressed by default.

Note: This is only available when href is not specified.
form form true string

Associates the button with a <form> element. The value should be the id of a <form> in the same document. If not set, the button is associated with its parent <form>, if any.

This attribute allows button elements to be associated with <form>s anywhere in the document, not just inside a <form>.

Note: Only available when href is not specified.
formaction formAction true string

Specifies the URL that processes the button's submitted information. Overrides the action attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".
formenctype formEnctype true 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain'

Specifies the form data encoding method. Possible values:

  • application/x-www-form-urlencoded: Default if the attribute is not used.
  • multipart/form-data: Used for <input> elements with type set to file.
  • text/plain: For debugging, not for real form submission.

Overrides the enctype attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".
formmethod formMethod true 'post' | 'get'

Specifies the HTTP method for form submission. Possible values:

  • post: Form data included in HTTP request body.
  • get: Form data appended to action URL.

Overrides the method attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".
formnovalidate formNoValidate true boolean false

Specifies that the form should not be validated on submission. Overrides the novalidate attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".
formtarget formTarget true '_self' | '_blank' | '_parent' | '_top'

Specifies where to display the form submission response. Possible values:

  • _self: Current browsing context. (Default).
  • _blank: New tab or window.
  • _parent: Parent browsing context or _self if no parent.
  • _top: Topmost browsing context or _self if no ancestors.

Overrides the target attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".
undefined validity false ValidityState

A ValidityState object that represents the element's validity states.
undefined validationMessage false string

The element's validation message. This is empty if the element meets its constraints.
### Methods
Name Description
click(): void

Simulates a mouse click on the element.
focus(options?: FocusOptions): void

Sets focus on the element. An optional parameter can be an object with a preventScroll property. If preventScroll is set to true, the page will not scroll to bring the focused element into view.
blur(): void

Removes focus from the element.
checkValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event and returns false. If it's valid, it returns true.
reportValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event, returns false, and displays a validation message. If it's valid, it returns true.
setCustomValidity(message: string): void

Sets a custom error message. If the text is non-empty, it indicates that the field is invalid.
### Events
Name Description
focus

Emitted when the FAB gains focus.
blur

Emitted when the FAB loses focus.
invalid

Emitted when the form control's validity is checked and it doesn't meet the constraints.
### Slots
Name Description
(default)

Text content.
icon

Icon.
### CSS Parts
Name Description
button

Internal <button> or <a> element.
label

Text on the right side.
icon

Icon on the left side.
loading

The <mdui-circular-progress> element for the loading state.
### CSS Custom Properties
Name Description
--shape-corner-small

The size of the component corner when size="small". You can use a specific pixel value, but it's recommended to reference design tokens.
--shape-corner-normal

The size of the component corner when size="normal". You can use a specific pixel value, but it's recommended to reference design tokens.
--shape-corner-large

The size of the component corner when size="large". You can use a specific pixel value, but it's recommended to reference design tokens.
# Icon Component The Icon component represents common actions and supports both Material Icons and SVG icons. ## Usage {#usage} Import the component: ```js import 'mdui/components/icon.js'; ``` Import the TypeScript type: ```ts import type { Icon } from 'mdui/components/icon.js'; ``` Example: ```html ``` ### Using Material Icons {#usage-material-icons} To use Material Icons, import the CSS file for the desired variant: Filled, Outlined, Rounded, Sharp, or Two Tone. ```html ``` Use the `name` attribute to specify the icon, appending the variant name as a suffix (no suffix needed for Filled). Here's how to use the `delete` icon in all 5 variants: ```html ``` Search for icons directly using the [Material Icons Search](/en/docs/2/components/icon#search) tool at the page bottom. Click an icon to copy its code to the clipboard. mdui also provides a standalone package [`@mdui/icons`](/en/docs/2/libraries/icons), with each icon component as a separate file. This allows importing only needed icon components, without the entire icon library. ### Using SVG Icon {#usage-svg} The component supports SVG icons. Pass the SVG icon link to the `src` attribute: ```html ``` Or, pass the SVG content directly into the component's default slot: ```html ``` ## Examples {#examples} ### Set Color {#example-color} Change the icon color by setting the `color` CSS style of the `` element or its parent. ```html ``` ### Set Size {#example-size} Change the icon size by setting the `font-size` CSS style of the `` element or its parent. ```html ``` ## mdui-icon API ### Properties
Attribute Property Reflect Type Default Description
name name true string

Specifies the name of the Material Icons.
src src true string

Specifies the path of the SVG icon.
### Slots
Name Description
(default)

The SVG icon content.
# Layout Component Layout components provide a flexible system for page-level layout. ## Usage {#usage} Import the component: ```js import 'mdui/components/layout.js'; import 'mdui/components/layout-item.js'; import 'mdui/components/layout-main.js'; ``` Import the TypeScript type: ```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'; ``` **Introduction:** The layout system is built from the outside in. Each layout component (``) occupies space in one of the four directions (top, bottom, left, right). Subsequent layout components continue to occupy the remaining space. The following components inherit from `` and can also be used as layout components: * [``](/en/docs/2/components/navigation-bar) * [``](/en/docs/2/components/navigation-drawer) * [``](/en/docs/2/components/navigation-rail) * [``](/en/docs/2/components/bottom-app-bar) * [``](/en/docs/2/components/top-app-bar) The `` component occupies the remaining space, where you can place page content. ## Examples {#examples} ### Layout Component Order {#layout-default-order} By default, layout components occupy space in the order they appear in the code. The following examples illustrate this concept, showing different orders for [``](/en/docs/2/components/top-app-bar) and [``](/en/docs/2/components/navigation-drawer).

View this example on a large screen.

```html Top App Bar Navigation drawer Main ``` ```html Navigation drawer Top App Bar Main ``` When [``](/en/docs/2/components/top-app-bar) is placed before [``](/en/docs/2/components/navigation-drawer), it occupies the full screen width first, leaving only the remaining height for ``. If their positions are swapped, [``](/en/docs/2/components/navigation-drawer) occupies the full screen height first, leaving only the remaining width for [``](/en/docs/2/components/top-app-bar). ### Layout Component Placement {#example-placement} Use the `placement` attribute to specify the position (top, bottom, left, or right) of the `` component in the layout. For [``](/en/docs/2/components/navigation-drawer) and [``](/en/docs/2/components/navigation-rail), the `placement` attribute specifies their left or right position. In the following example, two `` components are placed on both sides of the application. ```html Top App Bar Layout Item Layout Item Main ``` ### Custom Layout Component Order {#example-order} In most cases, the order of layout components in the code will achieve the desired layout. However, you can use the `order` attribute to specify the layout order. The system arranges the components in ascending order of `order` value. When `order` values are the same, it arranges them in the order they appear in the code. The default `order` for all layout components is `0`. ```html Layout Item Top App Bar
order="-1" Main ``` ## mdui-layout-item API ### Properties
Attribute Property Reflect Type Default Description
placement placement true 'top' | 'bottom' | 'left' | 'right' 'top'

Determines the component's position. Possible values:

  • top: Positions the component at the top.
  • bottom: Positions the component at the bottom.
  • left: Positions the component on the left.
  • right: Positions the component on the right.
order order true number

Specifies the layout order within the <mdui-layout> component. Items are sorted in ascending order. The default value is 0.
### Slots
Name Description
(default)

Can contains any content.
## mdui-layout-main API ### Slots
Name Description
(default)

Can contains any content.
## mdui-layout API ### Properties
Attribute Property Reflect Type Default Description
full-height fullHeight true boolean false

Sets the layout height to 100%.
### Slots
Name Description
(default)

Can contain elements such as <mdui-top-app-bar>, <mdui-bottom-app-bar>, <mdui-navigation-bar>, <mdui-navigation-drawer>, <mdui-navigation-rail>, <mdui-layout-item>, and <mdui-layout-main>.
# Linear Progress Component Linear progress indicators are horizontal bars that display the status of ongoing operations, such as data loading or form submission. ## Usage {#usage} Import the component: ```js import 'mdui/components/linear-progress.js'; ``` Import the TypeScript type: ```ts import type { LinearProgress } from 'mdui/components/linear-progress.js'; ``` Example: ```html ``` ## Examples {#examples} ### Determinate Progress {#example-value} By default, the linear progress indicator is in an indeterminate state. Use the `value` attribute to set the current progress. The default maximum progress value is `1`. ```html ``` Set the maximum progress value with the `max` attribute. ```html ``` ## mdui-linear-progress API ### Properties
Attribute Property Reflect Type Default Description
max max true number 1

Sets the maximum value for the progress indicator. The default value is 1.
value value false number

Sets the current value of the progress indicator. If not specified, the progress indicator is in an indeterminate state.
### CSS Parts
Name Description
indicator

The indicator part.
### CSS Custom Properties
Name Description
--shape-corner

The size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.
# List Component A List is a vertical arrangement of items that can contain text or images. ## Usage {#usage} Import the component: ```js import 'mdui/components/list.js'; import 'mdui/components/list-item.js'; import 'mdui/components/list-subheader.js'; ``` Import the TypeScript type: ```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'; ``` Example: ```html Subheader Item 1 Item 2 ``` ## Examples {#examples} ### Text Content {#example-text} The `headline` attribute on `` sets the primary text, while the `description` attribute sets the secondary text. ```html ``` Alternatively, use the default slot for the primary text and the `description` slot for the secondary text. ```html Headline Headline Supporting text ``` By default, both primary and secondary text are displayed in full. To limit the number of lines, use the `headline-line` and `description-line` attributes. The maximum limit is `3` lines. ```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 ``` ### Side Content {#example-side} The `icon` and `end-icon` attributes on `` add Material Icons to the left and right sides, respectively. ```html Headline ``` Alternatively, use the `icon` and `end-icon` slots to add elements to the left and right sides of the list item. ```html Headline ``` ### Link {#example-link} The `href` attribute turns the list into a link, with `download`, `target`, and `rel` attributes available for link-related functionality. ```html Headline ``` ### Disabled State {#example-disabled} The `disabled` attribute on `` disables the item. This also disables components within the list item. ```html Headline Headline ``` ### Active State {#example-active} The `active` attribute on `` activates the item. ```html Headline Headline ``` ### Nonclickable State {#example-nonclickable} The `nonclickable` attribute on `` removes mouse hover and click ripple effects. ```html Headline Headline ``` ### Rounded Shape {#example-rounded} The `rounded` attribute on `` gives the item a rounded appearance. ```html Headline Headline ``` ### Vertical Alignment {#example-alignment} The `alignment` attribute on `` aligns elements on the left and right. Possible values: * `start`: top alignment. * `center`: center alignment. * `end`: bottom alignment. ```html Headline Headline Headline ``` ### Custom Content {#example-custom} The `custom` slot in `` allows for full customization of the list item content. ```html
test
 ``` ## mdui-list-item API ### Properties
Attribute Property Reflect Type Default Description
headline headline true string

Main text. Alternatively, use the default slot.
headline-line headlineLine true 1 | 2 | 3

Line limit for main text. Truncates after exceeding. Default is no limit. Possible values:

  • 1: Single-line text, truncates after exceeding
  • 2: Double-line text, truncates after exceeding.
  • 3: Triple-line text, truncates after exceeding.
description description true string

Subtext. Alternatively, use slot="description".
description-line descriptionLine true 1 | 2 | 3

Line limit for subtext. Truncates after exceeding. Default is no limit. Possible values:

  • 1: Single-line text, truncates after exceeding
  • 2: Double-line text, truncates after exceeding.
  • 3: Triple-line text, truncates after exceeding.
icon icon true string

Material Icons name on the left. Alternatively, use slot="icon".
end-icon endIcon true string

Material Icons name on the right. Alternatively, use slot="end-icon".
disabled disabled true boolean false

Disables the list item. Grays out the item and disables elements like <mdui-checkbox>, <mdui-radio>, <mdui-switch>.
active active true boolean false

Activates the list item.
nonclickable nonclickable true boolean false

Makes the list item non-clickable. Elements like <mdui-checkbox>, <mdui-radio>, <mdui-switch> remain interactive.
rounded rounded true boolean false

Applies rounded style to the list item.
alignment alignment true 'start' | 'center' | 'end' 'center'

Vertical alignment of the list item. Possible values:

  • start: Top alignment.
  • center: Center alignment.
  • end: Bottom alignment.
href href true string

The URL for the hyperlink. If specified, the component renders as an <a> element and can use link-related attributes.
download download true string

Instructs the browser to treat the linked URL as a download.

Note: This is only available when href is specified.
target target true '_blank' | '_parent' | '_self' | '_top'

Defines where to display the linked URL. Possible values:

  • _blank: Opens in a new tab or window.
  • _parent: Opens in the parent browsing context or _self if no parent exists.
  • _self: Opens in the current browsing context. (Default).
  • _top: Opens in the topmost browsing context or _self if no ancestors exist.

Note: This is only available when href is specified.
rel rel true 'alternate' | 'author' | 'bookmark' | 'external' | 'help' | 'license' | 'me' | 'next' | 'nofollow' | 'noreferrer' | 'opener' | 'prev' | 'search' | 'tag'

Specifies the relationship of the linked URL as space-separated link types. Possible values:

  • alternate: Alternate versions of the current document.
  • author: Author of the current document or article.
  • bookmark: Permanent link for the nearest ancestor section.
  • external: The referenced document is not part of the same site as the current document.
  • help: Link to context-sensitive help.
  • license: Indicates that the main content of the current document is covered by the copyright license described by the referenced document.
  • me: Indicates that the current document represents the person who owns the linked content.
  • next: Indicates that the current document is part of a series and the next document in the series is the referenced document.
  • nofollow: Indicates that the current document's original author or publisher does not endorse the referenced document.
  • noreferrer: No Referer header will be included. Also has the same effect as noopener.
  • opener: Creates an auxiliary browsing context if the hyperlink would otherwise create a top-level browsing context that is not an auxiliary browsing context (i.e., has "_blank" as target attribute value).
  • prev: Indicates that the current document is part of a series and the previous document in the series is the referenced document.
  • search: Links to a resource that can be used to search through the current document and its related pages.
  • tag: Gives a tag (identified by the given address) that applies to the current document.

Note: This is only available when href is specified.
autofocus autofocus true boolean false

Determines if the element should be focused when the page loads.
tabindex tabIndex false number

Specifies the order in which the element receives focus when navigating with the Tab key.
### Methods
Name Description
click(): void

Simulates a mouse click on the element.
focus(options?: FocusOptions): void

Sets focus on the element. An optional parameter can be an object with a preventScroll property. If preventScroll is set to true, the page will not scroll to bring the focused element into view.
blur(): void

Removes focus from the element.
### Events
Name Description
focus

Emitted when the list item gains focus.
blur

Emitted when the list item loses focus.
### Slots
Name Description
(default)

Main text.
description

Subtext.
icon

Element on the left of the list item.
end-icon

Element on the right of the list item.
custom

Any custom content.
### CSS Parts
Name Description
container

List item container.
icon

Left icon.
end-icon

Right icon.
body

Middle part.
headline

Main title.
description

Subtitle.
### CSS Custom Properties
Name Description
--shape-corner

The size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.
--shape-corner-rounded

The size of the component corner when rounded is specified. You can use a specific pixel value, but it's recommended to reference design tokens.
## mdui-list-subheader API ### Slots
Name Description
(default)

Subheader text.
## mdui-list API ### Slots
Name Description
(default)

Contains <mdui-list-item> elements.
# Menu Component Menus display a list of choices on a temporary surface. They appear when users interact with a button, action, or other control. For dropdown menus, utilize the [``](/en/docs/2/components/dropdown) component. ## Usage {#usage} Import the component: ```js import 'mdui/components/menu.js'; import 'mdui/components/menu-item.js'; ``` Import the TypeScript type: ```ts import type { Menu } from 'mdui/components/menu.js'; import type { MenuItem } from 'mdui/components/menu-item.js'; ``` Example: ```html Item 1 Item 2 ``` ## Examples {#examples} ### Dropdown Menu {#example-dropdown} To create a dropdown menu, use the [``](/en/docs/2/components/dropdown) component. ```html open dropdown Item 1 Item 2 ``` ### Dense Style {#example-dense} For a dense menu style, add the `dense` attribute to ``. ```html Item 1 Item 2 Item 3 ``` ### Disabled Items {#example-disabled} To disable menu items, add the `disabled` attribute to ``. ```html Item 1 Item 2 Item 3 ``` ### Single Selection {#example-selects-single} For single selection, set the `selects` attribute to `single` on ``. The `value` of `` is the `value` of the selected ``. ```html Item 1 Item 2 ``` ### Multiple Selection {#example-selects-multiple} For multiple selection, set the `selects` attribute to `multiple` on ``. The `value` of `` is an array of the selected `` values. Note: For multiple selection, the `value` of `` is an array and can only be read and set via JavaScript property. ```html Item 1 Item 2 Item 3 ``` ### Icons {#example-icon} To add Material Icons on the left and right, add `icon`, `end-icon` attributes to ``. Use `end-text` attribute to add text on the right side. Alternatively, use `icon`, `end-icon`, `end-text` slots for the same purpose. Setting `icon` attribute to an empty string creates space for an icon on the left, aligning it with other items. ```html Item 1 Item 2 Ctrl+X Item 3 ``` For single or multiple selection, use `selected-icon` attribute or `selected-icon` slot to define the icon for selected state. ```html Item 1 Item 2 ``` ### Link {#example-link} To turn the menu item into a link, use the `href` attribute on the `` component. `download`, `target`, and `rel` attributes are available for link-related functionality. ```html Item 1 Item 2 ``` ### Submenu {#example-submenu} To specify submenu items, use the `submenu` slot within ``. ```html Line spacing Single 1.5 Double Custom: 1.2 Paragraph style ``` Set `submenu-trigger` attribute on `` to define the trigger method for the submenu. ```html Line spacing Single 1.5 Double Custom: 1.2 Paragraph style ``` When `submenu-trigger="hover"` is set, use `submenu-open-delay` and `submenu-close-delay` attributes on `` to set the delay for opening and closing the submenu. ```html Line spacing Single 1.5 Double Custom: 1.2 Paragraph style ``` ### Custom Content {#example-custom} To fully customize the menu item content, use the `custom` slot in ``. ```html
ABS
Absolute value of the number
ACOS
Arc cosine of the number, in radians
ACOSH
Inverse hyperbolic cosine of the number
 ``` ## mdui-menu-item API ### Properties
Attribute Property Reflect Type Default Description
value value true string

The value of the menu item.
disabled disabled true boolean false

Disables the menu item.
icon icon true string

Specifies the Material Icons name for the left icon. Alternatively, use slot="icon". An empty string reserves space for an icon.
end-icon endIcon true string

Specifies the Material Icons name for the right icon. Alternatively, use slot="end-icon".
end-text endText true string

Specifies the right text. Alternatively, use slot="end-text".
selected-icon selectedIcon true string

Specifies the Material Icons name for the selected state. Alternatively, use slot="selected-icon".
submenu-open submenuOpen true boolean false

Opens the submenu.
href href true string

The URL for the hyperlink. If specified, the component renders as an <a> element and can use link-related attributes.
download download true string

Instructs the browser to treat the linked URL as a download.

Note: This is only available when href is specified.
target target true '_blank' | '_parent' | '_self' | '_top'

Defines where to display the linked URL. Possible values:

  • _blank: Opens in a new tab or window.
  • _parent: Opens in the parent browsing context or _self if no parent exists.
  • _self: Opens in the current browsing context. (Default).
  • _top: Opens in the topmost browsing context or _self if no ancestors exist.

Note: This is only available when href is specified.
rel rel true 'alternate' | 'author' | 'bookmark' | 'external' | 'help' | 'license' | 'me' | 'next' | 'nofollow' | 'noreferrer' | 'opener' | 'prev' | 'search' | 'tag'

Specifies the relationship of the linked URL as space-separated link types. Possible values:

  • alternate: Alternate versions of the current document.
  • author: Author of the current document or article.
  • bookmark: Permanent link for the nearest ancestor section.
  • external: The referenced document is not part of the same site as the current document.
  • help: Link to context-sensitive help.
  • license: Indicates that the main content of the current document is covered by the copyright license described by the referenced document.
  • me: Indicates that the current document represents the person who owns the linked content.
  • next: Indicates that the current document is part of a series and the next document in the series is the referenced document.
  • nofollow: Indicates that the current document's original author or publisher does not endorse the referenced document.
  • noreferrer: No Referer header will be included. Also has the same effect as noopener.
  • opener: Creates an auxiliary browsing context if the hyperlink would otherwise create a top-level browsing context that is not an auxiliary browsing context (i.e., has "_blank" as target attribute value).
  • prev: Indicates that the current document is part of a series and the previous document in the series is the referenced document.
  • search: Links to a resource that can be used to search through the current document and its related pages.
  • tag: Gives a tag (identified by the given address) that applies to the current document.

Note: This is only available when href is specified.
autofocus autofocus true boolean false

Determines if the element should be focused when the page loads.
tabindex tabIndex false number

Specifies the order in which the element receives focus when navigating with the Tab key.
### Methods
Name Description
click(): void

Simulates a mouse click on the element.
focus(options?: FocusOptions): void

Sets focus on the element. An optional parameter can be an object with a preventScroll property. If preventScroll is set to true, the page will not scroll to bring the focused element into view.
blur(): void

Removes focus from the element.
### Events
Name Description
focus

Emitted when the menu item gains focus.
blur

Emitted when the menu item loses focus.
submenu-open

Emitted when the submenu starts to open. Can be prevented with event.preventDefault().
submenu-opened

Emitted after the submenu has opened and the animations are completed.
submenu-close

Emitted when the submenu starts to close. Can be prevented with event.preventDefault().
submenu-closed

Emitted after the submenu has closed and the animations are completed.
### Slots
Name Description
(default)

Menu item text.
icon

Left icon.
end-icon

Right icon.
end-text

Right text.
selected-icon

Icon for the selected state.
submenu

Submenu.
custom

Any custom content.
### CSS Parts
Name Description
container

Menu item container.
icon

Left icon.
label

Text content.
end-icon

Right icon.
end-text

Right text.
selected-icon

Icon for the selected state.
submenu

Submenu element.
## mdui-menu API ### Properties
Attribute Property Reflect Type Default Description
selects selects true 'single' | 'multiple'

Defines the selectable state of menu items. Defaults to non-selectable. Possible values:

  • single: Only one item can be selected at a time.
  • multiple: Multiple items can be selected.
value value false string | string[]

The value of the selected <mdui-menu-item>.

Note: The HTML attribute is always a string and can only be set as an initial value when selects="single". The JavaScript property value is a string when selects="single" and an array of strings when selects="multiple". In selects="multiple", this value can only be modified by changing the JavaScript property.
dense dense true boolean false

Indicates whether the menu items use a compact layout.
submenu-trigger submenuTrigger true 'click' | 'hover' | 'focus' | 'manual' | string 'click hover'

Defines the trigger method for submenus. Supports multiple values separated by spaces. Possible values:

  • click: Open submenu when clicking on a menu item.
  • hover: Open submenu when hovering over a menu item.
  • focus: Open submenu when focusing on a menu item.
  • manual: Only programmatically open and close submenus, no other trigger methods can be specified.
submenu-open-delay submenuOpenDelay true number 200

Specifies the delay (in milliseconds) for opening a submenu via hover.
submenu-close-delay submenuCloseDelay true number 200

Specifies the delay (in milliseconds) for closing a submenu via hover.
### Methods
Name Description
focus(options?: FocusOptions): void

Sets focus on the element.
blur(): void

Remove focus from the element.
### Events
Name Description
change

Emitted when the selected state of menu items changes
### Slots
Name Description
(default)

Submenu items (<mdui-menu-item>), dividers (<mdui-divider>), and other elements.
### CSS Custom Properties
Name Description
--shape-corner

The size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.
# Navigation Bar Component The navigation bar facilitates easy switching between main pages on mobile devices. ## Usage {#usage} Import the component: ```js import 'mdui/components/navigation-bar.js'; import 'mdui/components/navigation-bar-item.js'; ``` Import the TypeScript type: ```ts import type { NavigationBar } from 'mdui/components/navigation-bar.js'; import type { NavigationBarItem } from 'mdui/components/navigation-bar-item.js'; ``` Example: (Note: The `style="position: relative"` in the example is for demonstration purposes. Remove it in actual use.) ```html Item 1 Item 2 Item 3 ``` **Note:** By default, this component uses a `position: fixed` style and automatically adds a `padding-bottom` style to the `body` to prevent page content from being obscured. However, it uses a `position: absolute` style in the following cases: 1. When the `scroll-target` attribute is specified. In this case, `padding-bottom` is added to the specified element. 2. When it's inside the [``](/en/docs/2/components/layout) component. In this case, `padding-bottom` is not added. ## Examples {#examples} ### Label Visibility {#example-label-visibility} Text labels in the navigation bar are always visible when there are 3 or fewer navigation items. If there are more than 3 items, only the text of the selected item is displayed. ```html Item 1 Item 2 Item 3
Item 1 Item 2 Item 3 Item 4 ``` The `label-visibility` attribute on `` controls the visibility of text labels. Possible values: * `selected`: Only the text of the selected item is displayed. * `labeled`: Text is always displayed. * `unlabeled`: Text is never displayed. ```html Item 1 Item 2 Item 3 selected labeled unlabeled ``` ### In Container {#example-scroll-target} By default, the navigation bar is relative to the current window and appears at the bottom of the page. If you want to place the navigation bar within a specific container, use the `scroll-target` attribute on ``. The value should be the CSS selector or DOM element of the container with scrollable content. In this case, the navigation bar will be relative to the parent element. You need to manually add the styles `position: relative; overflow: hidden` to the parent element. ```html
Item 1 Item 2 Item 3
Page content
``` ### Hide on Scroll {#example-scroll-behavior} The `scroll-behavior` attribute on `` controls the visibility of the navigation bar during scrolling. Set its value to `hide` to hide the navigation bar when scrolling down and show it when scrolling up. The `scroll-threshold` attribute sets the number of pixels to start hiding the navigation bar. ```html
Item 1 Item 2 Item 3
Page content
``` ### Icons {#example-icon} The `icon` attribute on `` sets the icon for the inactive state. The `active-icon` attribute sets the icon for the active state. Alternatively, use the `icon` and `active-icon` slots to set the icons for the inactive and active states. ```html Item 1 Item 2 ``` ### Link {#example-link} Use the `href` attribute on the `` component to turn the navigation item into a link. The `download`, `target`, and `rel` attributes are available for link-related functionality. ```html Item 1 Item 2 ``` ### Badge {#example-badge} You can add a badge to the `` component using the `badge` slot. ```html Item 1 99+ Item 2 ``` ## mdui-navigation-bar-item API ### Properties
Attribute Property Reflect Type Default Description
icon icon true string

Specifies the Material Icons name for the inactive state. Alternatively, use slot="icon".
active-icon activeIcon true string

Specifies the Material Icons name for the active state. Alternatively, use slot="active-icon".
value value true string

The value of the navigation item.
href href true string

The URL for the hyperlink. If specified, the component renders as an <a> element and can use link-related attributes.
download download true string

Instructs the browser to treat the linked URL as a download.

Note: This is only available when href is specified.
target target true '_blank' | '_parent' | '_self' | '_top'

Defines where to display the linked URL. Possible values:

  • _blank: Opens in a new tab or window.
  • _parent: Opens in the parent browsing context or _self if no parent exists.
  • _self: Opens in the current browsing context. (Default).
  • _top: Opens in the topmost browsing context or _self if no ancestors exist.

Note: This is only available when href is specified.
rel rel true 'alternate' | 'author' | 'bookmark' | 'external' | 'help' | 'license' | 'me' | 'next' | 'nofollow' | 'noreferrer' | 'opener' | 'prev' | 'search' | 'tag'

Specifies the relationship of the linked URL as space-separated link types. Possible values:

  • alternate: Alternate versions of the current document.
  • author: Author of the current document or article.
  • bookmark: Permanent link for the nearest ancestor section.
  • external: The referenced document is not part of the same site as the current document.
  • help: Link to context-sensitive help.
  • license: Indicates that the main content of the current document is covered by the copyright license described by the referenced document.
  • me: Indicates that the current document represents the person who owns the linked content.
  • next: Indicates that the current document is part of a series and the next document in the series is the referenced document.
  • nofollow: Indicates that the current document's original author or publisher does not endorse the referenced document.
  • noreferrer: No Referer header will be included. Also has the same effect as noopener.
  • opener: Creates an auxiliary browsing context if the hyperlink would otherwise create a top-level browsing context that is not an auxiliary browsing context (i.e., has "_blank" as target attribute value).
  • prev: Indicates that the current document is part of a series and the previous document in the series is the referenced document.
  • search: Links to a resource that can be used to search through the current document and its related pages.
  • tag: Gives a tag (identified by the given address) that applies to the current document.

Note: This is only available when href is specified.
autofocus autofocus true boolean false

Determines if the element should be focused when the page loads.
tabindex tabIndex false number

Specifies the order in which the element receives focus when navigating with the Tab key.
### Methods
Name Description
click(): void

Simulates a mouse click on the element.
focus(options?: FocusOptions): void

Sets focus on the element. An optional parameter can be an object with a preventScroll property. If preventScroll is set to true, the page will not scroll to bring the focused element into view.
blur(): void

Removes focus from the element.
### Events
Name Description
focus

Emitted when the navigation bar item gains focus.
blur

Emitted when the navigation bar item loses focus.
### Slots
Name Description
(default)

Text.
icon

Icon.
active-icon

Icon for the active state.
badge

Badge.
### CSS Parts
Name Description
container

Container for the navigation item.
indicator

Indicator.
badge

Badge.
icon

Icon.
active-icon

Icon for the active state.
label

Text.
### CSS Custom Properties
Name Description
--shape-corner-indicator

The size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.
## mdui-navigation-bar API ### Properties
Attribute Property Reflect Type Default Description
hide hide true boolean false

Hides the navigation bar when set.
label-visibility labelVisibility true 'auto' | 'selected' | 'labeled' | 'unlabeled' 'auto'

Specifies the visibility of the text. Possible values:

  • auto: Visible if there are 3 or fewer options, otherwise only the selected state is visible.
  • selected: Only visible in the selected state.
  • labeled: Always visible.
  • unlabeled: Never visible.
value value true string

The value of the selected <mdui-navigation-bar-item>.
scroll-behavior scrollBehavior true 'hide' | 'shrink' | 'elevate'

Defines the scroll behavior. Possible values:

  • hide: Hides when scrolling.
scroll-target scrollTarget false string | HTMLElement | JQ<HTMLElement>

The element that listens for scroll events. Accepts a CSS selector, DOM element, or JQ object. Defaults to window.
scroll-threshold scrollThreshold true number

The scroll distance (in pixels) that triggers the scroll behavior.
order order true number

Specifies the layout order within the <mdui-layout> component. Items are sorted in ascending order. The default value is 0.
### Events
Name Description
change

Emitted when the value changes.
show

Emitted when the navigation bar starts to show. Can be prevented with event.preventDefault().
shown

Emitted after the navigation bar has shown and animations are complete.
hide

Emitted when the navigation bar starts to hide. Can be prevented with event.preventDefault().
hidden

Emitted after the navigation bar has hidden and animations are complete.
### Slots
Name Description
(default)

Contains <mdui-navigation-bar-item> components.
### CSS Custom Properties
Name Description
--shape-corner

The size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.
--z-index

The CSS z-index value of the component.
# Navigation Drawer Component The navigation drawer provides a side-access method to different pages on a webpage. Typically, the [``](/en/docs/2/components/list) component is used within the navigation drawer to add navigation items. ## Usage {#usage} Import the component: ```js import 'mdui/components/navigation-drawer.js'; ``` Import the TypeScript type: ```ts import type { NavigationDrawer } from 'mdui/components/navigation-drawer.js'; ``` Example: ```html Close Navigation Drawer Open Navigation Drawer ``` **Notes:** This component defaults to a `position: fixed` style. When the `modal` attribute is set to `false` and the breakpoint is equal to or greater than [`--mdui-breakpoint-md`](/en/docs/2/styles/design-tokens#breakpoint), it automatically adds `padding-left` or `padding-right` to the body to prevent content from being obscured. However, it uses a `position: absolute` style in the following cases: 1. When the `contained` property is `true`. 2. When it's within the [``](/en/docs/2/components/layout) component. In this case, it doesn't add `padding-left` or `padding-right`. ## Examples {#examples} ### In Container {#example-contained} By default, the navigation drawer displays on the left or right side of the current window. To place it inside a container, add the `contained` attribute. This positions the navigation drawer relative to the parent element (you need to manually add `position: relative; overflow: hidden;` styles to the parent element). ```html
Close Navigation Drawer
Open Navigation Drawer
``` ### Modal {#example-modal} The `modal` attribute displays a modal overlay when the navigation drawer is open. Note that if the window or parent element width is less than [`--mdui-breakpoint-md`](/en/docs/2/styles/design-tokens#breakpoint), this attribute is ignored and the modal overlay is always displayed. The `close-on-esc` attribute allows the navigation drawer to close when the ESC key is pressed. The `close-on-overlay-click` attribute allows the navigation drawer to close when the modal overlay is clicked. ```html
Close Navigation Drawer
Open Navigation Drawer
``` ### Right Placement {#example-placement} Set the `placement` attribute to `right` to display the navigation drawer on the right side. ```html
Close Navigation Drawer
Open Navigation Drawer
``` ## mdui-navigation-drawer API ### Properties
Attribute Property Reflect Type Default Description
open open true boolean false

Opens the navigation drawer.
modal modal true boolean false

Displays an overlay when open.

On narrow devices (screen width < --mdui-breakpoint-md), the overlay always displays.
close-on-esc closeOnEsc true boolean false

Closes the drawer when the ESC key is pressed and an overlay is present.
close-on-overlay-click closeOnOverlayClick true boolean false

Closes the drawer when the overlay is clicked.
placement placement true 'left' | 'right' 'left'

Sets the drawer's display position. Possible values:

  • left: Display on the left side.
  • right: Display on the right side.
contained contained true boolean false

By default, the navigation drawer displays relative to the body element. When set, it displays relative to its parent element.

Note: You must add position: relative; overflow: hidden; style to the parent element when this attribute is set.
order order true number

Specifies the layout order within the <mdui-layout> component. Items are sorted in ascending order. The default value is 0.
### Events
Name Description
open

Emitted when the navigation drawer starts to open. Can be prevented with event.preventDefault().
opened

Emitted after the navigation drawer has opened and the animations are completed.
close

Emitted when the navigation drawer starts to close. Can be prevented with event.preventDefault().
closed

Emitted after the navigation drawer has closed and the animations are completed.
overlay-click

Emitted when the overlay is clicked.
### Slots
Name Description
(default)

Contents of the navigation drawer.
### CSS Parts
Name Description
overlay

Overlay element.
panel

Container for the navigation drawer.
### CSS Custom Properties
Name Description
--shape-corner

The size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.
--z-index

The CSS z-index value of the component.
# Navigation Rail Component The navigation rail provides a means to access different primary pages on tablets and desktop computers. ## Usage {#usage} Import the component: ```js import 'mdui/components/navigation-rail.js'; import 'mdui/components/navigation-rail-item.js'; ``` Import the TypeScript type: ```ts import type { NavigationRail } from 'mdui/components/navigation-rail.js'; import type { NavigationRailItem } from 'mdui/components/navigation-rail-item.js'; ``` Example: (Note: The `style="position: relative"` in the example is for demonstration purposes, Remove it in actual use.) ```html Recent Images Library ``` **Notes:** By default, this component uses the `position: fixed` style and automatically adds `padding-left` or `padding-right` to the `body` to prevent content obscuration. However, it defaults to `position: absolute` style in the following cases: 1. When the `contained` property of the `` component is `true`. In this case, it adds `padding-left` or `padding-right` style to the parent element. 2. When it's within the [``](/en/docs/2/components/layout) component. In this case, it doesn't add `padding-left` or `padding-right` style. ## Styles {#examples} ### In Container {#example-contained} By default, the navigation rail displays on the left or right side of the current window. To place it inside a container, add the `contained` attribute to the `` component. This positions the navigation rail relative to the parent element (you need to manually add `position: relative` style to the parent element). ```html
Recent Images Library
Page Content
``` ### Right Placement {#example-placement} Set the `placement` attribute of the `` component to `right` to display the navigation rail on the right. ```html
Recent Images Library
Page Content
``` ### Display a Divider {#example-divider} Add the `divider` attribute to the `` component to add a divider to the navigation rail, distinguishing it from the page content. ```html
Recent Images Library
Page Content
``` ### Top/Bottom Elements {#example-top-bottom} Inside the `` component, you can use the `top` and `bottom` slots to add elements at the top and bottom. ```html
Recent Images Library
Page Content
``` ### Vertical Alignment {#example-alignment} Set the `alignment` attribute of the `` component to modify the vertical alignment of navigation items. ```html
Recent Images Library
start center end
``` ### Icons {#example-icon} Use the `icon` attribute on the `` component to set the icon for the inactive state of the navigation item. The `active-icon` attribute sets the icon for the active state. Alternatively, use the `icon` and `active-icon` slots for the inactive and active states respectively. ```html
Recent Images Library
Page Content
``` ### Icon Only {#example-no-label} The `` component can display icons without labels. ```html
Page Content
``` ### Link {#example-link} Use the `href` attribute on the `` component to turn the navigation item into a link. The `download`, `target`, and `rel` attributes are available for link-related functionality. ```html
Recent Images Library
Page Content
``` ### Badge {#example-badge} Add a badge to the `` component using the `badge` slot. ```html
Recent 99+ Images Library
Page Content
``` ## mdui-navigation-rail-item API ### Properties
Attribute Property Reflect Type Default Description
icon icon true string

Specifies the Material Icons name for the inactive state. Alternatively, use slot="icon".
active-icon activeIcon true string

Specifies the Material Icons name for the active state. Alternatively, use slot="active-icon".
value value true string

The value of the navigation item.
href href true string

The URL for the hyperlink. If specified, the component renders as an <a> element and can use link-related attributes.
download download true string

Instructs the browser to treat the linked URL as a download.

Note: This is only available when href is specified.
target target true '_blank' | '_parent' | '_self' | '_top'

Defines where to display the linked URL. Possible values:

  • _blank: Opens in a new tab or window.
  • _parent: Opens in the parent browsing context or _self if no parent exists.
  • _self: Opens in the current browsing context. (Default).
  • _top: Opens in the topmost browsing context or _self if no ancestors exist.

Note: This is only available when href is specified.
rel rel true 'alternate' | 'author' | 'bookmark' | 'external' | 'help' | 'license' | 'me' | 'next' | 'nofollow' | 'noreferrer' | 'opener' | 'prev' | 'search' | 'tag'

Specifies the relationship of the linked URL as space-separated link types. Possible values:

  • alternate: Alternate versions of the current document.
  • author: Author of the current document or article.
  • bookmark: Permanent link for the nearest ancestor section.
  • external: The referenced document is not part of the same site as the current document.
  • help: Link to context-sensitive help.
  • license: Indicates that the main content of the current document is covered by the copyright license described by the referenced document.
  • me: Indicates that the current document represents the person who owns the linked content.
  • next: Indicates that the current document is part of a series and the next document in the series is the referenced document.
  • nofollow: Indicates that the current document's original author or publisher does not endorse the referenced document.
  • noreferrer: No Referer header will be included. Also has the same effect as noopener.
  • opener: Creates an auxiliary browsing context if the hyperlink would otherwise create a top-level browsing context that is not an auxiliary browsing context (i.e., has "_blank" as target attribute value).
  • prev: Indicates that the current document is part of a series and the previous document in the series is the referenced document.
  • search: Links to a resource that can be used to search through the current document and its related pages.
  • tag: Gives a tag (identified by the given address) that applies to the current document.

Note: This is only available when href is specified.
autofocus autofocus true boolean false

Determines if the element should be focused when the page loads.
tabindex tabIndex false number

Specifies the order in which the element receives focus when navigating with the Tab key.
### Methods
Name Description
click(): void

Simulates a mouse click on the element.
focus(options?: FocusOptions): void

Sets focus on the element. An optional parameter can be an object with a preventScroll property. If preventScroll is set to true, the page will not scroll to bring the focused element into view.
blur(): void

Removes focus from the element.
### Events
Name Description
focus

Emitted when the navigation rail item gains focus.
blur

Emitted when the navigation rail item loses focus.
### Slots
Name Description
(default)

Text.
icon

Icon.
active-icon

Icon for the active state.
badge

Badge.
### CSS Parts
Name Description
container

Container for the navigation item.
indicator

Indicator.
badge

Badge.
icon

Icon.
active-icon

Icon for the active state.
label

Text.
### CSS Custom Properties
Name Description
--shape-corner-indicator

The size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.
## mdui-navigation-rail API ### Properties
Attribute Property Reflect Type Default Description
value value true string

The value of the selected <mdui-navigation-rail-item>.
placement placement true 'left' | 'right' 'left'

Sets the navigation bar's position. Possible values:

  • left: Display on the left.
  • right: Display on the right.
alignment alignment true 'start' | 'center' | 'end' 'start'

Sets the alignment of <mdui-navigation-rail-item>. Possible values:

  • start: Aligns to the top.
  • center: Aligns to the center.
  • end: Aligns to the bottom.
contained contained true boolean false

By default, the navigation rail displays relative to the body element. When set, it displays relative to its parent element.

Note: You must add position: relative; overflow: hidden; style to the parent element when this attribute is set.
divider divider true boolean false

Adds a divider between the navigation bar and the page content.
order order true number

Specifies the layout order within the <mdui-layout> component. Items are sorted in ascending order. The default value is 0.
### Events
Name Description
change

Emitted when the value changes.
### Slots
Name Description
(default)

Contains <mdui-navigation-rail-item> components.
top

Top element.
bottom

Bottom element.
### CSS Parts
Name Description
top

Container for the top element.
bottom

Container for the bottom element.
items

Container for <mdui-navigation-rail-item> components.
### CSS Custom Properties
Name Description
--shape-corner

The size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.
--z-index

The CSS z-index value of the component.
# Radio Component The radio group component is designed for selecting a single option from a set of options. ## Usage {#usage} Import the component: ```js import 'mdui/components/radio-group.js'; import 'mdui/components/radio.js'; ``` Import the TypeScript type: ```ts import type { RadioGroup } from 'mdui/components/radio-group.js'; import type { Radio } from 'mdui/components/radio.js'; ``` Example: ```html Chinese English ``` ## Examples {#examples} ### Checked State {#example-checked} The `value` property of the `` component corresponds to the `value` of the currently selected `` component. You can change the selected radio button by updating the `value` property of the `` component. ```html Chinese English ``` The `` component can also be used independently. In this case, use the `checked` property to access and modify the checked state. ```html Radio ``` ### Disabled State {#example-disabled} To disable the entire radio group, add the `disabled` attribute to the `` component. ```html Chinese English ``` To disable a specific radio button, add the `disabled` attribute to the `` component. ```html Chinese English ``` ### Icons {#example-icon} You can set Material Icons for the unchecked and checked states of the radio button using the `unchecked-icon` and `checked-icon` attributes, respectively. Alternatively, you can use the `unchecked-icon` and `checked-icon` slots. ```html Chinese English ``` ## mdui-radio-group API ### Properties
Attribute Property Reflect Type Default Description
disabled disabled true boolean false

Disables the radio group when set.
form form true string

Associates the radio group with a <form> element. The value should be the id of a <form> in the same document. If not set, the radio group is associated with its parent <form>, if any.

This attribute allows radio group elements to be associated with <form>s anywhere in the document, not just inside a <form>.
name name true string ''

The name of the radio group, which is submitted with form data.
value value true string ''

The value of the selected radio button, which is submitted with form data.
undefined defaultValue false string ''

The default selected value. Resets to this value when form is reset. This value can only be set via JavaScript property.
required required true boolean false

Requires a radio selection when the form is submitted.
undefined validity false ValidityState

A ValidityState object that represents the element's validity states.
undefined validationMessage false string

The element's validation message. This is empty if the element meets its constraints.
### Methods
Name Description
checkValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event and returns false. If it's valid, it returns true.
reportValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event, returns false, and displays a validation message. If it's valid, it returns true.
setCustomValidity(message: string): void

Sets a custom error message. If the text is non-empty, it indicates that the field is invalid.
### Events
Name Description
change

Emitted when the selected value changes.
input

Emitted when the selected value changes.
invalid

Emitted when the form control's validity is checked and it doesn't meet the constraints.
### Slots
Name Description
(default)

<mdui-radio> elements.
## mdui-radio API ### Properties
Attribute Property Reflect Type Default Description
value value true string ''

Specifies the value of the radio.
disabled disabled true boolean false

Disables the radio when set.
checked checked true boolean false

Sets the radio to the checked state.
unchecked-icon uncheckedIcon true string

Specifies the Material Icons name for the unchecked state. Alternatively, use slot="unchecked-icon".
checked-icon checkedIcon true string

Specifies the Material Icons name for the checked state. Alternatively, use slot="checked-icon".
autofocus autofocus true boolean false

Determines if the element should be focused when the page loads.
tabindex tabIndex false number

Specifies the order in which the element receives focus when navigating with the Tab key.
### Methods
Name Description
click(): void

Simulates a mouse click on the element.
focus(options?: FocusOptions): void

Sets focus on the element. An optional parameter can be an object with a preventScroll property. If preventScroll is set to true, the page will not scroll to bring the focused element into view.
blur(): void

Removes focus from the element.
### Events
Name Description
focus

Emitted when the radio gains focus.
blur

Emitted when the radio loses focus.
change

Emitted when the radio is selected.
### Slots
Name Description
(default)

Text content.
unchecked-icon

Icon for the unchecked state.
checked-icon

Icon for the checked state.
### CSS Parts
Name Description
control

Container for the left icon.
unchecked-icon

Icon for the unchecked state.
checked-icon

Icon for the checked state.
label

Text content.
# Range Slider Component The Range Slider component allows users to select a range from a series of values. ## Usage {#usage} Import the component: ```js import 'mdui/components/range-slider.js'; ``` Import the TypeScript type: ```ts import type { RangeSlider } from 'mdui/components/range-slider.js'; ``` Example: ```html ``` ## Examples {#examples} ### Default Value {#example-value} The `value` property represents the current value of the range slider. You can set the range slider's value by updating the `value` property. Note that the `value` property is an array and can only be accessed and modified through JavaScript property. ```html ``` ### Disabled State {#example-disabled} The range slider can be disabled by adding the `disabled` attribute. ```html ``` ### Range {#example-min-max} The `min` and `max` attributes allow you to set the minimum and maximum values of the range slider. ```html ``` ### Step Interval {#example-step} The `step` attribute defines the interval of the range slider. ```html ``` ### Tickmarks {#example-tickmarks} Tickmarks can be displayed on the range slider by adding the `tickmarks` attribute. ```html ``` ### Hide Tooltip {#example-nolabel} The tooltip on the range slider can be hidden by adding the `nolabel` attribute. ```html ``` ### Modify Tooltip {#example-labelFormatter} The `labelFormatter` property allows you to customize the display format of the tooltip. This property is a function that takes the current value of the range slider as a parameter and returns the text you want to display. ```html ``` ## mdui-range-slider API ### Properties
Attribute Property Reflect Type Default Description
undefined defaultValue false number[] []

Specifies the default value. Resets to this state when the form is reset. This value can only be set via JavaScript property.
undefined value false number[]

Specifies the slider value in array format. This value is submitted with form data. It can't be set with HTML attributes initially, only via JavaScript property.
autofocus autofocus true boolean false

Determines if the element should be focused when the page loads.
tabindex tabIndex false number

Specifies the order in which the element receives focus when navigating with the Tab key.
min min true number 0

Specifies the minimum value. Default is 0.
max max true number 100

Specifies the maximum value. Default is 100.
step step true number 1

Specifies the step interval. Default is 1.
tickmarks tickmarks true boolean false

Adds tickmarks to the slider.
nolabel nolabel true boolean false

Hides the tooltip.
disabled disabled true boolean false

Disables the slider.
form form true string

Associates the slider with a <form> element. The value should be the id of a <form> in the same document. If not set, the slider is associated with its parent <form>, if any.

This attribute allows slider elements to be associated with <form>s anywhere in the document, not just inside a <form>.
name name true string ''

Specifies the slider's name, which is submitted with the form data.
undefined validity false ValidityState

A ValidityState object that represents the element's validity states.
undefined validationMessage false string

The element's validation message. This is empty if the element meets its constraints.
undefined labelFormatter false (value: number) => string

Specifies a function to format the tooltip's value. The function should take the slider's value as an argument and return a string to display in the tooltip.
### Methods
Name Description
click(): void

Simulates a mouse click on the element.
focus(options?: FocusOptions): void

Sets focus on the element. An optional parameter can be an object with a preventScroll property. If preventScroll is set to true, the page will not scroll to bring the focused element into view.
blur(): void

Removes focus from the element.
checkValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event and returns false. If it's valid, it returns true.
reportValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event, returns false, and displays a validation message. If it's valid, it returns true.
setCustomValidity(message: string): void

Sets a custom error message. If the text is non-empty, it indicates that the field is invalid.
### Events
Name Description
focus

Emitted when the range slider gains focus.
blur

Emitted when the range slider loses focus.
change

Emitted when the value changes and the range slider loses focus.
input

Emitted when the value changes.
invalid

Emitted when the form control's validity is checked and it doesn't meet the constraints.
### CSS Parts
Name Description
track-inactive

Track for the inactive state.
track-active

Track for the active state.
handle

Handle for interaction.
label

Tooltip text.
tickmark

Tick mark.
# Select Component The Select component is designed to present a list of options in a dropdown menu. This guide focuses on the usage of the `` component. For information on dropdown menu items, please refer to the [``](/en/docs/2/components/menu#menu-item-api) section. ## Usage {#usage} Import the component: ```js import 'mdui/components/select.js'; import 'mdui/components/menu-item.js'; ``` Import the TypeScript type: ```ts import type { Select } from 'mdui/components/select.js'; import type { MenuItem } from 'mdui/components/menu-item.js'; ``` Example: ```html Item 1 Item 2 ``` ## Examples {#examples} ### Variants {#example-variant} The `variant` attribute allows you to modify the shape of the select. ```html Item 1 Item 2 Item 1 Item 2 ``` ### Multiple Selection {#example-multiple} By default, the component is set to single-select. The `value` of the `` component corresponds to the `value` of the currently selected [``](/en/docs/2/components/menu#menu-item-api). To enable multi-select, add the `multiple` attribute. In this case, the `value` of `` becomes an array containing the `value` properties of the currently selected [``](/en/docs/2/components/menu#menu-item-api) components. Note: When multiple selections are enabled, the `value` of `` is an array. This value can only be read and set using JavaScript properties. ```html Item 1 Item 2 Item 3 ``` ### Helper Text {#example-helper-text} The `label` attribute allows you to display label text above the select. ```html Item 1 Item 2 ``` The `placeholder` attribute allows you to display placeholder text when no value is selected. ```html Item 1 Item 2 ``` The `helper` attribute allows you to display helper text at the bottom of the select. Alternatively, use the `helper` slot to set helper text. ```html Item 1 Item 2 Item 1 Item 2 Supporting text ``` ### Read-Only State {#example-readonly} To make the select read-only, add the `readonly` attribute. ```html Item 1 Item 2 ``` ### Disabled State {#example-disabled} To disable the select, add the `disabled` attribute. ```html Item 1 Item 2 ``` ### Clearable {#example-clearable} The `clearable` attribute adds a clear button on the right when the select has a value. ```html Item 1 Item 2 ``` You can customize the clear button using the `clear` slot. ```html Item 1 Item 2 ``` ### Dropdown Menu Position {#example-placement} You can set the dropdown menu position using the `placement` attribute. ```html Item 1 Item 2 ``` ### Text Alignment {#example-end-aligned} To align the text to the right, add the `end-aligned` attribute. ```html Item 1 Item 2 ``` ### Prefix, Suffix, and Icons {#example-prefix-suffix} You can add Material Icons to the left and right of the select by setting the `icon` and `end-icon` attributes. Alternatively, use the `icon` and `end-icon` slots to add elements to the select. ```html Item 1 Item 2

Item 1 Item 2 ``` You can add text to the left and right of the select by setting the `prefix` and `suffix` attributes. Alternatively, use the `prefix` and `suffix` slots to add text elements. This text is displayed when the select is focused or has a value. ```html Item 1 Item 2

Item 1 Item 2 $ /100 ``` ## mdui-select API ### Properties
Attribute Property Reflect Type Default Description
variant variant true 'filled' | 'outlined' 'filled'

Defines the select style. Possible values:

  • filled: Solid background, strong visual emphasis.
  • outlined: Bordered, less visual emphasis.
multiple multiple true boolean false

Enables multiple selections.
name name true string ''

Name of the select, which is submitted with form data.
value value false string | string[] ''

Value of the select, which is submitted with form data.

If multiple is not set, the value is a string; if set, it's an array of strings. HTML attributes can only set string values; array values must be set via JavaScript property.
undefined defaultValue false string | string[] ''

Default selected value. Resets to this value when form is reset. Can only be set via JavaScript property.
label label true string

Label text.
placeholder placeholder true string

Placeholder text.
helper helper true string

Helper text displayed below the select. Alternatively, use slot="helper".
clearable clearable true boolean false

Allows the select to be cleared.
clear-icon clearIcon true string

Material Icons name for the clear button displayed on the right of the select when clearable. Alternatively, use slot="clear-icon".
placement placement true 'auto' | 'bottom' | 'top' 'auto'

Select placement. Possible values:

  • auto: Automatically determined.
  • bottom: Below the input.
  • top: Above the input.
end-aligned endAligned true boolean false

Aligns text to the right.
prefix prefix true string

Prefix text of the select. Displayed only when the select is focused or has a value. Alternatively, use slot="prefix".
suffix suffix true string

Suffix text of the select. Displayed only when the select is focused or has a value. Alternatively, use slot="suffix".
icon icon true string

Material Icons name for the prefix icon. Alternatively, use slot="icon".
end-icon endIcon true string

Material Icons name for the suffix icon. Alternatively, use slot="end-icon".
error-icon errorIcon true string

Material Icons name displayed on the right when form field validation fails. Alternatively, use slot="error-icon".
form form true string

Associates the select with a <form> element. The value should be the id of a <form> in the same document. If not set, the select is associated with its parent <form>, if any.

This attribute allows select elements to be associated with <form>s anywhere in the document, not just inside a <form>.
readonly readonly true boolean false

Makes the select read-only.
disabled disabled true boolean false

Disables the select.
required required true boolean false

Requires a selection when the form is submitted.
undefined validity false ValidityState

A ValidityState object that represents the element's validity states.
undefined validationMessage false string

The element's validation message. This is empty if the element meets its constraints.
autofocus autofocus true boolean false

Determines if the element should be focused when the page loads.
tabindex tabIndex false number

Specifies the order in which the element receives focus when navigating with the Tab key.
### Methods
Name Description
checkValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event and returns false. If it's valid, it returns true.
reportValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event, returns false, and displays a validation message. If it's valid, it returns true.
setCustomValidity(message: string): void

Sets a custom error message. If the text is non-empty, it indicates that the field is invalid.
click(): void

Simulates a mouse click on the element.
focus(options?: FocusOptions): void

Sets focus on the element. An optional parameter can be an object with a preventScroll property. If preventScroll is set to true, the page will not scroll to bring the focused element into view.
blur(): void

Removes focus from the element.
### Events
Name Description
focus

Emitted when the select gains focus.
blur

Emitted when the select loses focus.
change

Emitted when the selected value changes.
invalid

Emitted when the form control's validity is checked and it doesn't meet the constraints.
clear

Emitted when the clear button is clicked. Can be prevented with event.preventDefault().
### Slots
Name Description
(default)

<mdui-menu-item> elements.
icon

Left icon.
end-icon

Right icon.
error-icon

Right icon when validation fails.
prefix

Left text.
suffix

Right text.
clear-button

Clear button.
clear-icon

Icon in the clear button.
helper

Bottom helper text.
### CSS Parts
Name Description
chips

Container for option chips when multiple is enabled.
chip

Individual chip representing each multiselect option.
chip__button

The <button> element within the chip.
chip__label

Text part of the chip.
chip__delete-icon

Delete icon within the chip.
text-field

Text field, i.e., <mdui-text-field> element.
text-field__container

Container for the text field.
text-field__icon

Icon within the text field.
text-field__end-icon

Right-side icon within the text field.
text-field__error-icon

Icon displayed in the text field upon validation failure.
text-field__prefix

Text on the left side of the text field.
text-field__suffix

Text on the right side of the text field.
text-field__label

Label text displayed above the text field.
text-field__input

The <input> element within the text field.
text-field__clear-button

Clear button within the text field.
text-field__clear-icon

Icon within the clear button of the text field.
text-field__supporting

Container for supporting information at the bottom of the text field, including helper and error messages.
text-field__helper

Helper text displayed at the bottom of the text field.
text-field__error

Error message displayed at the bottom of the text field.
menu

Dropdown menu, i.e., <mdui-menu> element.
# Segmented Button Component The segmented button group is a component that encapsulates a set of buttons. It is used to provide options, switch views, or sort elements. ## Usage {#usage} Import the component: ```js import 'mdui/components/segmented-button-group.js'; import 'mdui/components/segmented-button.js'; ``` Import the TypeScript type: ```ts import type { SegmentedButtonGroup } from 'mdui/components/segmented-button-group.js'; import type { SegmentedButton } from 'mdui/components/segmented-button.js'; ``` Example: ```html Day Week Month ``` ## Examples {#examples} ### Full Width {#example-full-width} To make the component take up the full width of its container, add the `full-width` attribute to the `` component. ```html Day Week Month ``` ### Single Selection {#example-selects-single} To enable single selection mode, set the `selects` attribute of the `` component to `single`. In this mode, the `value` property of `` reflects the `value` property of the currently selected ``. ```html Day Week Month Day Week Month ``` ### Multiple Selection {#example-selects-multiple} To enable multiple selection mode, set the `selects` attribute of the `` component to `multiple`. In this mode, the `value` property of `` is an array consisting of the `value` properties of the currently selected `` components. Note that when supporting multiple selection, the `value` property of `` is an array, and it can only be read and set through JavaScript property. ```html Day Week Month Day Week Month ``` ### Icons {#example-icon} To add Material Icons on the left and right sides of the button, use the `icon` and `end-icon` attributes on the `` element. Alternatively, use the `icon` and `end-icon` slots to add elements on the left and right sides of the button. ```html Day Week Month ``` To set the Material Icon for the selected state, use the `selected-icon` attribute on the `` element. Alternatively, use the `selected-icon` slot. ```html Day Week ``` ### Link {#example-link} To turn the button into a link, use the `href` attribute on the `` component. The `download`, `target`, and `rel` attributes are available for link-related functionality. ```html Link Week Month ``` ### Disabled and Loading States {#example-disabled} To disable the entire segmented button group, add the `disabled` attribute to the `` element. ```html Day Week Month ``` To disable specific buttons, add the `disabled` attribute to the `` element. To make a button enter the loading state, add the `loading` attribute. ```html Day Week Month Year ``` ## mdui-segmented-button-group API ### Properties
Attribute Property Reflect Type Default Description
full-width fullWidth true boolean false

If set, the segmented button group will fill the width of its parent element.
selects selects true 'single' | 'multiple'

Defines selectable states. Default is non-selectable. Possible values:

  • single: Only one can be selected.
  • multiple: Multiple selections are allowed.
disabled disabled true boolean false

Disables the segmented button group when set.
required required true boolean false

Requires a selection when the form is submitted.
form form true string

Associates the segmented button group with a <form> element. The value should be the id of a <form> in the same document. If not set, the segmented button group is associated with its parent <form>, if any.

This attribute allows segmented button group elements to be associated with <form>s anywhere in the document, not just inside a <form>.
name name true string ''

The name of the segmented button group, which is submitted with form data.
value value false string | string[] ''

The value of the selected <mdui-segmented-button>. This value is submitted with form data.

Note: The HTML attribute is always a string and can only be set as an initial value when selects="single". The JavaScript property is a string when selects="single" and an array of strings when selects="multiple". In selects="multiple", this value can only be modified by changing the JavaScript property.
undefined defaultValue false string | string[] ''

The default selected value. Resets to this state when the form is reset. This value can only be set via JavaScript property.
undefined validity false ValidityState

A ValidityState object that represents the element's validity states.
undefined validationMessage false string

The element's validation message. This is empty if the element meets its constraints.
### Methods
Name Description
checkValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event and returns false. If it's valid, it returns true.
reportValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event, returns false, and displays a validation message. If it's valid, it returns true.
setCustomValidity(message: string): void

Sets a custom error message. If the text is non-empty, it indicates that the field is invalid.
### Events
Name Description
change

Emitted when the selected value changes.
invalid

Emitted when the form control's validity is checked and it doesn't meet the constraints.
### Slots
Name Description
(default)

<mdui-segmented-button> elements.
### CSS Custom Properties
Name Description
--shape-corner

The size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.
## mdui-segmented-button API ### Properties
Attribute Property Reflect Type Default Description
icon icon true string

Specifies the Material Icons name for the left icon. Alternatively, use slot="icon".
end-icon endIcon true string

Specifies the Material Icons name for the right icon. Alternatively, use slot="end-icon".
selected-icon selectedIcon true string

Specifies the Material Icons name for the selected state. Alternatively, use slot="selected-icon".
href href true string

The URL for the hyperlink. If provided, the component is rendered as an <a> element and can use link-related attributes.
download download true string

Instructs the browser to download the linked URL.

Note: This is only available when href is specified.
target target true '_blank' | '_parent' | '_self' | '_top'

Defines where to open the linked URL. Possible values:

  • _blank: Opens in a new tab or window.
  • _parent: Opens in the parent browsing context or _self if no parent.
  • _self: Opens in the current browsing context. (Default).
  • _top: Opens in the topmost browsing context or _self if no ancestors.

Note: This is only available when href is specified.
rel rel true 'alternate' | 'author' | 'bookmark' | 'external' | 'help' | 'license' | 'me' | 'next' | 'nofollow' | 'noreferrer' | 'opener' | 'prev' | 'search' | 'tag'

Specifies the relationship of the linked URL as space-separated link types. Possible values:

  • alternate: Alternate versions of the current document.
  • author: The author of the current document or article.
  • bookmark: The permalink for the nearest ancestor section.
  • external: The referenced document is not part of the same site as the current document.
  • help: A link to context-sensitive help.
  • license: Indicates that the main content of the current document is covered by the copyright license described by the referenced document.
  • me: Indicates that the current document represents the person who owns the linked content.
  • next: Indicates that the current document is part of a series and the next document in the series is the referenced document.
  • nofollow: Indicates that the current document's original author or publisher does not endorse the referenced document.
  • noreferrer: No Referer header will be included. Also has the same effect as noopener.
  • opener: Creates an auxiliary browsing context if the hyperlink would otherwise create a top-level browsing context that is not an auxiliary browsing context (i.e., has "_blank" as target attribute value).
  • prev: Indicates that the current document is part of a series and the previous document in the series is the referenced document.
  • search: Links to a resource that can be used to search through the current document and its related pages.
  • tag: Gives a tag (identified by the given address) that applies to the current document.

Note: This is only available when href is specified.
autofocus autofocus true boolean false

Specifies that the element should be focused when the page loads.
tabindex tabIndex false number

Defines the order in which the element receives focus when navigating with the Tab key.
disabled disabled true boolean false

Disables the element.
loading loading true boolean false

Indicates that the element is in a loading state.
name name true string ''

The button's name, which is submitted with form data.

Note: This is only available when href is not specified.
value value true string ''

The button's value, which is submitted with form data.

Note: This is only available when href is not specified.
type type true 'submit' | 'reset' | 'button' 'button'

Defines the button's default behavior. The default is button. Possible values:

  • submit: Submits the form data to the server.
  • reset: Resets all the controls to their initial values.
  • button: No default behavior, does nothing when pressed by default.

Note: This is only available when href is not specified.
form form true string

Associates the button with a <form> element. The value should be the id of a <form> in the same document. If not set, the button is associated with its parent <form>, if any.

This attribute allows button elements to be associated with <form>s anywhere in the document, not just inside a <form>.

Note: Only available when href is not specified.
formaction formAction true string

Specifies the URL that processes the button's submitted information. Overrides the action attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".
formenctype formEnctype true 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain'

Specifies the form data encoding method. Possible values:

  • application/x-www-form-urlencoded: Default if the attribute is not used.
  • multipart/form-data: Used for <input> elements with type set to file.
  • text/plain: For debugging, not for real form submission.

Overrides the enctype attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".
formmethod formMethod true 'post' | 'get'

Specifies the HTTP method for form submission. Possible values:

  • post: Form data included in HTTP request body.
  • get: Form data appended to action URL.

Overrides the method attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".
formnovalidate formNoValidate true boolean false

Specifies that the form should not be validated on submission. Overrides the novalidate attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".
formtarget formTarget true '_self' | '_blank' | '_parent' | '_top'

Specifies where to display the form submission response. Possible values:

  • _self: Current browsing context. (Default).
  • _blank: New tab or window.
  • _parent: Parent browsing context or _self if no parent.
  • _top: Topmost browsing context or _self if no ancestors.

Overrides the target attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".
undefined validity false ValidityState

A ValidityState object that represents the element's validity states.
undefined validationMessage false string

The element's validation message. This is empty if the element meets its constraints.
### Methods
Name Description
click(): void

Simulates a mouse click on the element.
focus(options?: FocusOptions): void

Sets focus on the element. An optional parameter can be an object with a preventScroll property. If preventScroll is set to true, the page will not scroll to bring the focused element into view.
blur(): void

Removes focus from the element.
checkValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event and returns false. If it's valid, it returns true.
reportValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event, returns false, and displays a validation message. If it's valid, it returns true.
setCustomValidity(message: string): void

Sets a custom error message. If the text is non-empty, it indicates that the field is invalid.
### Events
Name Description
focus

Emitted when the segmented button gains focus.
blur

Emitted when the segmented button loses focus.
invalid

Emitted when the form control's validity is checked and it doesn't meet the constraints.
### Slots
Name Description
(default)

Text content.
icon

Left icon.
selected-icon

Icon for the selected state.
end-icon

Right icon.
### CSS Parts
Name Description
button

Internal <button> or <a> element.
icon

Left icon.
selected-icon

Icon for the selected state.
end-icon

Right icon.
label

Text content.
loading

The <mdui-circular-progress> element for the loading state.
# Slider Component Sliders provide a way for users to select from a range of values. ## Usage {#usage} Import the component: ```js import 'mdui/components/slider.js'; ``` Import the TypeScript type: ```ts import type { Slider } from 'mdui/components/slider.js'; ``` Example: ```html ``` ## Examples {#examples} ### Default Value {#example-value} The `value` property allows you to read or set the slider's value. ```html ``` ### Disabled State {#example-disabled} The `disabled` attribute can be used to disable the slider. ```html ``` ### Range {#example-min-max} The `min` and `max` attributes allow you to set the slider's minimum and maximum values. ```html ``` ### Step Interval {#example-step} The `step` attribute allows you to set the slider's step interval. ```html ``` ### Tickmarks {#example-tickmarks} The `tickmarks` attribute can be used to add tickmarks to the slider. ```html ``` ### Hide Tooltip {#example-nolabel} The `nolabel` attribute can be used to hide the slider's tooltip. ```html ``` ### Modify Tooltip {#example-labelFormatter} The `labelFormatter` property allows you to modify the tooltip's display format. This property is a function that takes the slider's current value as a parameter and returns the display text. ```html ``` ## mdui-slider API ### Properties
Attribute Property Reflect Type Default Description
value value false number 0

The value of the slider, which is submitted with form data.
undefined defaultValue false number 0

The default value. The slider resets to this value when the form is reset. This can only be set via a JavaScript property.
autofocus autofocus true boolean false

Determines if the element should be focused when the page loads.
tabindex tabIndex false number

Specifies the order in which the element receives focus when navigating with the Tab key.
min min true number 0

Specifies the minimum value. Default is 0.
max max true number 100

Specifies the maximum value. Default is 100.
step step true number 1

Specifies the step interval. Default is 1.
tickmarks tickmarks true boolean false

Adds tickmarks to the slider.
nolabel nolabel true boolean false

Hides the tooltip.
disabled disabled true boolean false

Disables the slider.
form form true string

Associates the slider with a <form> element. The value should be the id of a <form> in the same document. If not set, the slider is associated with its parent <form>, if any.

This attribute allows slider elements to be associated with <form>s anywhere in the document, not just inside a <form>.
name name true string ''

Specifies the slider's name, which is submitted with the form data.
undefined validity false ValidityState

A ValidityState object that represents the element's validity states.
undefined validationMessage false string

The element's validation message. This is empty if the element meets its constraints.
undefined labelFormatter false (value: number) => string

Specifies a function to format the tooltip's value. The function should take the slider's value as an argument and return a string to display in the tooltip.
### Methods
Name Description
click(): void

Simulates a mouse click on the element.
focus(options?: FocusOptions): void

Sets focus on the element. An optional parameter can be an object with a preventScroll property. If preventScroll is set to true, the page will not scroll to bring the focused element into view.
blur(): void

Removes focus from the element.
checkValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event and returns false. If it's valid, it returns true.
reportValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event, returns false, and displays a validation message. If it's valid, it returns true.
setCustomValidity(message: string): void

Sets a custom error message. If the text is non-empty, it indicates that the field is invalid.
### Events
Name Description
focus

Emitted when the slider gains focus.
blur

Emitted when the slider loses focus.
change

Emitted when the value changes and the slider loses focus.
input

Emitted when the value changes.
invalid

Emitted when the form control's validity is checked and it doesn't meet the constraints.
### CSS Parts
Name Description
track-inactive

Inactive track.
track-active

Active track.
handle

Slider handle.
label

Prompt text.
tickmark

Tick mark.
# Snackbar Component Snackbars provide brief updates about app processes at the bottom of the screen. In addition to direct component usage, mdui also offers a [`mdui.snackbar`](/en/docs/2/functions/snackbar) function for simplified Snackbar component usage. ## Usage {#usage} Import the component: ```js import 'mdui/components/snackbar.js'; ``` Import the TypeScript type: ```ts import type { Snackbar } from 'mdui/components/snackbar.js'; ``` Example: ```html Photo archived Open Snackbar ``` ## Examples {#examples} ### Position {#example-placement} You can set the snackbar's position using the `placement` attribute. ```html
Photo archived top-start Photo archived top Photo archived top-end
Photo archived bottom-start Photo archived bottom Photo archived bottom-end
``` ### Action Button {#example-action} The `action` attribute adds an action button on the right side and specifies its text. The `action-click` event is triggered when the action button is clicked. The `action-loading` attribute displays a loading state on the action button. ```html Photo archived Open Snackbar ``` The `action` slot can also be used to add elements on the right side. ```html Photo archived Undo Open Snackbar ``` ### Closable {#example-closeable} The `closeable` attribute adds a close button on the right. Clicking the button closes the snackbar and triggers the `close` event. ```html Photo archived Open Snackbar ``` The `close-button` slot specifies the element of the close button. ```html Photo archived Open Snackbar ``` The `close-icon` attribute sets the Material Icon in the default close button. The `close-icon` slot sets the icon element in the default close button. ```html Photo archived Open Snackbar ``` ### Text Lines {#example-message-line} The `message-line` attribute limits the number of lines in the message text, with a maximum of `2` lines. ```html The item already has the label "travel". You can add a new label. You can add a new label. Open Snackbar ``` ### Auto Close Delay {#example-auto-close-delay} The `auto-close-delay` attribute sets the delay for automatic closure, in milliseconds. The default is `5000` milliseconds. ```html Photo archived Open Snackbar ``` ### Closing on Outside Click {#example-close-on-outside-click} The `close-on-outside-click` attribute closes the snackbar when clicking outside of its area. ```html Photo archived Open Snackbar ``` ## mdui-snackbar API ### Properties
Attribute Property Reflect Type Default Description
open open true boolean false

Opens the Snackbar.
placement placement true 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' 'bottom'

Snackbar placement. Default is bottom. Possible values:

  • top: Top, centered.
  • top-start: Top, left-aligned.
  • top-end: Top, right-aligned.
  • bottom: Bottom, centered.
  • bottom-start: Bottom, left-aligned.
  • bottom-end: Bottom, right-aligned.
action action true string

Text for the action button. Alternatively, use slot="action".
action-loading actionLoading true boolean false

Indicates if the action button is in the loading state.
closeable closeable true boolean false

Shows a close button on the right.
close-icon closeIcon true string

Material Icons name for the close button. Alternatively, use slot="close-icon".
message-line messageLine true 1 | 2

Maximum lines for message text. Default is unlimited. Possible values:

  • 1: Single line.
  • 2: Two lines.
auto-close-delay autoCloseDelay true number 5000

Automatically closes the Snackbar after a specified time (in milliseconds). Set to 0 to disable auto-closing. Default is 5 seconds.
close-on-outside-click closeOnOutsideClick true boolean false

Closes the Snackbar when clicking or touching outside the Snackbar area.
### Events
Name Description
open

Emitted when the snackbar starts to open. Can be prevented with event.preventDefault().
opened

Emitted after the snackbar opens and animations complete.
close

Emitted when the snackbar starts to close. Can be prevented with event.preventDefault().
closed

Emitted after the snackbar closes and animations complete.
action-click

Emitted when the action button is clicked.
### Slots
Name Description
(default)

Snackbar message.
action

Right action button.
close-button

Right close button. Displayed if closeable is set
close-icon

Icon in right close button.
### CSS Parts
Name Description
message

Message text.
action

Action button.
close-button

Close button.
close-icon

Icon in the close button.
### CSS Custom Properties
Name Description
--shape-corner

The size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.
--z-index

The CSS z-index value of the component.
# Switch Component The Switch component is utilized to toggle the state of a single setting between on and off. ## Usage {#usage} Import the component: ```js import 'mdui/components/switch.js'; ``` Import the TypeScript type: ```ts import type { Switch } from 'mdui/components/switch.js'; ``` Example: ```html ``` ## Examples {#examples} ### Checked State {#example-checked} The `checked` attribute indicates whether the switch is on or off. To set the switch to the on state by default, add the `checked` attribute. ```html ``` ### Disabled State {#example-disabled} The `disabled` attribute can be used to disable the switch. ```html ``` ### Icons {#example-icon} The `unchecked-icon` and `checked-icon` attributes can be used to set the Material Icons for the unchecked and checked states, respectively. Alternatively, the `unchecked-icon` and `checked-icon` slots can be used to set the icons for the unchecked and checked states. ```html ``` ## mdui-switch API ### Properties
Attribute Property Reflect Type Default Description
disabled disabled true boolean false

Disables the switch.
checked checked true boolean false

Sets the switch to the checked state.
undefined defaultChecked false boolean false

The default checked state. The switch resets to this state when the form is reset. This can only be set via a JavaScript property.
unchecked-icon uncheckedIcon true string

The Material Icons name for the unchecked state. Alternatively, use slot="unchecked-icon".
checked-icon checkedIcon true string

The Material Icons name for the checked state. Alternatively, use slot="checked-icon". Defaults to the check icon; an empty string removes the default icon.
required required true boolean false

The switch must be checked when submitting the form.
form form true string

Associates the switch with a <form> element. The value should be the id of a <form> in the same document. If not set, the switch is associated with its parent <form>, if any.

This attribute allows switch elements to be associated with <form>s anywhere in the document, not just inside a <form>.
name name true string ''

The name of the switch, which is submitted with form data.
value value true string 'on'

The value of the switch, which is submitted with form data.
undefined validity false ValidityState

A ValidityState object that represents the element's validity states.
undefined validationMessage false string

The element's validation message. This is empty if the element meets its constraints.
autofocus autofocus true boolean false

Determines if the element should be focused when the page loads.
tabindex tabIndex false number

Specifies the order in which the element receives focus when navigating with the Tab key.
### Methods
Name Description
checkValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event and returns false. If it's valid, it returns true.
reportValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event, returns false, and displays a validation message. If it's valid, it returns true.
setCustomValidity(message: string): void

Sets a custom error message. If the text is non-empty, it indicates that the field is invalid.
click(): void

Simulates a mouse click on the element.
focus(options?: FocusOptions): void

Sets focus on the element. An optional parameter can be an object with a preventScroll property. If preventScroll is set to true, the page will not scroll to bring the focused element into view.
blur(): void

Removes focus from the element.
### Events
Name Description
focus

Emitted when the switch gains focus.
blur

Emitted when the switch loses focus.
change

Emitted when the checked state changes.
input

Emitted when the checked state changes.
invalid

Emitted when the form control's validity is checked and it doesn't meet the constraints.
### Slots
Name Description
unchecked-icon

Element for the unchecked state.
checked-icon

Element for the checked state.
### CSS Parts
Name Description
track

Track.
thumb

Icon container.
unchecked-icon

Icon for the unchecked state.
checked-icon

Icon for the checked state.
### CSS Custom Properties
Name Description
--shape-corner

The corner size of the track. You can use a specific pixel value, but it's recommended to reference design tokens.
--shape-corner-thumb

The corner size of the icon container. You can use a specific pixel value, but it's recommended to reference design tokens.
# Tabs Component Tabs organize content across different screens and views. ## Usage {#usage} Import the component: ```js import 'mdui/components/tabs.js'; import 'mdui/components/tab.js'; import 'mdui/components/tab-panel.js'; ``` Import the TypeScript type: ```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'; ``` Example: ```html Tab 1 Tab 2 Tab 3 Panel 1 Panel 2 Panel 3 ``` ## Examples {#examples} ### Variant {#example-variant} The `variant` attribute on the `` component allows you to set the style of the tabs. ```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 ``` ### Tab Placement {#example-placement} The `placement` attribute on the `` component allows you to set the position of the tabs. ```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 ``` ### Full Width {#example-full-width} To make the tabs occupy the entire width and be evenly distributed, add the `full-width` attribute to the `` component. ```html Tab 1 Tab 2 Tab 3 Panel 1 Panel 2 Panel 3 ``` ### Icons {#example-icon} Add Material Icons to the tabs by setting the `icon` attribute on the `` component. Alternatively, use the `icon` slot to add icon elements. Arrange the icon and text horizontally by adding the `inline` attribute. ```html Tab 1 Tab 2 Tab 3 Panel 1 Panel 2 Panel 3 ``` ### Badge {#example-badge} Add a badge to the `` component using the `badge` slot. ```html Tab 1 99+ Tab 2 Tab 3 Panel 1 Panel 2 Panel 3 ``` ### Custom Content {#example-custom} Use the `custom` slot in the `` component to fully customize the content of the tabs. ```html Tab 1 Icon Tab 2 Tab 3 Panel 1 Panel 2 Panel 3 ``` ## mdui-tab-panel API ### Properties
Attribute Property Reflect Type Default Description
value value true string

Specifies the value of the tab panel.
### Slots
Name Description
(default)

The content of the tab panel.
## mdui-tab API ### Properties
Attribute Property Reflect Type Default Description
value value true string

Specifies the tab value.
icon icon true string

Specifies the Material Icons name. Alternatively, use slot="icon".
inline inline true boolean false

Arranges the icon and text horizontally.
autofocus autofocus true boolean false

Determines if the element should be focused when the page loads.
tabindex tabIndex false number

Specifies the order in which the element receives focus when navigating with the Tab key.
### Methods
Name Description
click(): void

Simulates a mouse click on the element.
focus(options?: FocusOptions): void

Sets focus on the element. An optional parameter can be an object with a preventScroll property. If preventScroll is set to true, the page will not scroll to bring the focused element into view.
blur(): void

Removes focus from the element.
### Events
Name Description
focus

Emitted when the tab gains focus.
blur

Emitted when the tab loses focus.
### Slots
Name Description
(default)

Tab text.
icon

Tab icon.
badge

Badge.
custom

Custom tab content.
### CSS Parts
Name Description
container

Tab container.
icon

Tab icon.
label

Tab text.
## mdui-tabs API ### Properties
Attribute Property Reflect Type Default Description
variant variant true 'primary' | 'secondary' 'primary'

Defines the tab shape. Possible values:

  • primary: Located below <mdui-top-app-bar>, used for switching between main application pages.
  • secondary: Located within the page, used for switching between related content groups.
value value true string

Specifies the active <mdui-tab> value.
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'

Defines the tab position. Default is top-start. Possible values:

  • top-start: Top, left-aligned.
  • top: Top, center-aligned.
  • top-end: Top, right-aligned.
  • bottom-start: Bottom, left-aligned.
  • bottom: Bottom, center-aligned.
  • bottom-end: Bottom, right-aligned.
  • left-start: Left, top-aligned.
  • left: Left, center-aligned.
  • left-end: Left, bottom-aligned.
  • right-start: Right, top-aligned.
  • right: Right, center-aligned.
  • right-end: Right, bottom-aligned.
full-width fullWidth true boolean false

If set, the tabs will fill the width of its parent element.
### Events
Name Description
change

Emitted when the selected value changes.
### Slots
Name Description
(default)

<mdui-tab> elements.
panel

<mdui-tab-panel> elements.
### CSS Parts
Name Description
container

Container for <mdui-tab> elements.
indicator

Indicator for the active state.
# TextField Component Text fields, typically used in forms and dialogs, allow users to input text. ## Usage {#usage} Import the component: ```js import 'mdui/components/text-field.js'; ``` Import the TypeScript type: ```ts import type { TextField } from 'mdui/components/text-field.js'; ``` Example: ```html ``` ## Examples {#examples} ### Variant {#example-variant} The `variant` attribute modifies the shape of the text field. ```html

``` ### Helper Text {#example-helper-text} The `label` attribute sets the label text above the text field. ```html ``` The `placeholder` attribute sets the placeholder text when there is no value. ```html ``` The `helper` attribute or `helper` slot sets the helper text at the bottom of the text field. To display the helper text only when the input is focused, use the `helper-on-focus` attribute. ```html Supporting text ``` ### Clearable {#example-clearable} The `clearable` attribute adds a clear button on the right when the text field has a value. ```html ``` ### End-Aligned Text {#example-end-aligned} The `end-aligned` attribute aligns the text to the right. ```html ``` ### Prefix, Suffix, Icons {#example-prefix-suffix} The `icon` and `end-icon` attributes or slots add Material Icons to the left and right of the text field, respectively. ```html

``` The `prefix` and `suffix` attributes or slots add text to the left and right of the text field. This text is displayed only when the text field is focused or has a value. ```html

$ /100 ``` ### Readonly {#example-readonly} The `readonly` attribute makes the text field read-only. ```html ``` ### Disabled {#example-disabled} The `disabled` attribute disables the text field. ```html ``` ### Multi-line Text Field {#example-rows} The `rows` attribute sets the number of rows for a multi-line text field. ```html ``` To automatically adjust the height of the text field based on the length of the input, use the `autosize` attribute. The `min-rows` and `max-rows` attributes specify the minimum and maximum number of rows. ```html

``` ### Character Counter {#example-counter} The `maxlength` attribute sets the maximum number of characters for the text field. To display a character counter below the text field, use the `counter` attribute. ```html ``` ### Password Field {#example-password} For password fields (`type="password"`), the `toggle-password` attribute adds a button on the right to toggle the visibility of the password. ```html ``` ## mdui-text-field API ### Properties
Attribute Property Reflect Type Default Description
variant variant true 'filled' | 'outlined' 'filled'

Defines the text field style. Default is filled. Possible values:

  • filled: Text field with background color, providing a stronger visual effect.
  • outlined: Text field with border, providing a subtler visual effect.
type type true 'text' | 'number' | 'password' | 'url' | 'email' | 'search' | 'tel' | 'hidden' | 'date' | 'datetime-local' | 'month' | 'time' | 'week' 'text'

Specifies the text field type. Default is text. Possible values:

  • text: Standard text field.
  • number: Allows only numeric input. Devices with dynamic keyboards will display a numeric keyboard.
  • password: Masks the input for password confidentiality.
  • url: Validates URL format. Devices with dynamic keyboards will display a URL-specific keyboard.
  • email: Validates email format. Devices with dynamic keyboards will display an email-specific keyboard.
  • search: Changes the enter icon to a search icon on devices with dynamic keyboards.
  • tel: Displays a phone number keyboard on devices with dynamic keyboards.
  • hidden: Hides the control, but its value will still be submitted to the server.
  • date: Activates a date picker or a numeric scroll wheel for year, month, and day in supported browsers.
  • datetime-local: Activates a date and time picker in supported browsers, excluding time zone.
  • month: Allows input for year and month, excluding time zone.
  • time: Allows time input, excluding time zone.
  • week: Allows input for dates consisting of a year and week, excluding time zone.
name name true string ''

The name of text field, which is submitted with form data.
value value false string ''

The value of text field, which is submitted with form data.
undefined defaultValue false string ''

The default value. The text field resets to this value on form reset. This can only be set via the JavaScript property.
label label true string

Label text.
placeholder placeholder true string

Placeholder text.
helper helper true string

The helper text displayed at the bottom of the text field. Alternatively, use slot="helper".
helper-on-focus helperOnFocus true boolean false

If set, the helper text is only displayed when the text field is focused.
clearable clearable true boolean false

If set, the text field can be cleared.
clear-icon clearIcon true string

Material Icons name displayed on the right when the text field is clearable. Alternatively, use slot="clear-icon".
end-aligned endAligned true boolean false

Aligns the text to the right.
prefix prefix true string

The prefix text for the text field. It is only displayed when the text field is focused or has a value. Alternatively, use slot="prefix".
suffix suffix true string

The suffix text for the text field. It is only displayed when the text field is focused or has a value. Alternatively, use slot="suffix".
icon icon true string

Material Icons name for the prefix icon of the text field. Alternatively, use slot="icon".
end-icon endIcon true string

Material Icons name for the suffix icon of the text field. Alternatively, use slot="end-icon".
error-icon errorIcon true string

Material Icons name displayed on the right side of the text field when the form field validation fails. Alternatively, use slot="error-icon".
form form true string

Associates the text field with a <form> element. The value should be the id of a <form> in the same document. If not set, the text field is associated with its parent <form>, if any.

This attribute allows text field elements to be associated with <form>s anywhere in the document, not just inside a <form>.
readonly readonly true boolean false

Makes the text field read-only.
disabled disabled true boolean false

Disables the text field.
required required true boolean false

The field must be filled in before the form is submitted.
rows rows true number

The number of rows in the text field.
autosize autosize true boolean false

Allows the text field height to adjust automatically based on the input content.
min-rows minRows true number

The minimum number of rows when autosize is enabled.
max-rows maxRows true number

The maximum number of rows when autosize is enabled.
minlength minlength true number

The minimum number of characters for input.
maxlength maxlength true number

The maximum number of characters for input.
counter counter true boolean false

Displays the character count when maxlength is specified.
min min true number

The minimum value when type is number.
max max true number

The maximum value when type is number.
step step true number

The step interval during increment and decrement when type is number.
pattern pattern true string

The regular expression for form validation.
toggle-password togglePassword true boolean false

Adds a toggle button for showing and hiding the password when type is password.
show-password-icon showPasswordIcon true string

Material Icons name for the visible password toggle button. Alternatively, use slot="show-password-icon".
hide-password-icon hidePasswordIcon true string

Material Icons name for the hidden password toggle button. Alternatively, use slot="hide-password-icon".
autocapitalize autocapitalize true 'none' | 'sentences' | 'words' | 'characters'

A non-standard iOS attribute for automatic capitalization. Possible values:

  • none: Disables automatic capitalization.
  • sentences: Capitalizes the first letter of each sentence.
  • words: Capitalizes the first letter of each word.
  • characters: Capitalizes all letters.
autocorrect autocorrect true string

The autocorrect attribute of the input element.
autocomplete autocomplete true string

The autocomplete attribute of the input element.
enterkeyhint enterkeyhint true 'enter' | 'done' | 'go' | 'next' | 'previous' | 'search' | 'send'

Customizes the Enter key text or icon on the virtual keyboard. The effect varies based on the device and language. Possible values:

  • enter: Inserts a new line, typically used in a multi-line text field.
  • done: Indicates input completion, closes the virtual keyboard.
  • go: Navigates to the target of the entered text.
  • next: Moves to the next text field.
  • previous: Moves to the previous text field.
  • search: Navigates to search results.
  • send: Sends a text message.
spellcheck spellcheck true boolean false

Enable spell checking.
inputmode inputmode true 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url'

Customizes the virtual keyboard. Possible values:

  • none: No virtual keyboard. This is useful for custom input controls.
  • text: Standard text input keyboard.
  • decimal: Decimal input keyboard. This includes a period . or comma , and numbers.
  • numeric: Numeric keyboard. This displays numbers 0-9.
  • tel: Phone number keyboard. This includes numbers 0-9, asterisk *, and hash # keys.
  • search: Search-optimized virtual keyboard. 'Search' is displayed on the submit button.
  • email: Email-optimized virtual keyboard. This typically includes @ ..
  • url: URL-optimized virtual keyboard. This typically includes . / #.
undefined validity false ValidityState

A ValidityState object that represents the element's validity states.
undefined validationMessage false string

The element's validation message. This is empty if the element meets its constraints.
undefined valueAsNumber false number

Gets or sets the value as a number. Returns NaN if the value cannot be converted.
autofocus autofocus true boolean false

Determines if the element should be focused when the page loads.
tabindex tabIndex false number

Specifies the order in which the element receives focus when navigating with the Tab key.
### Methods
Name Description
select(): void

Selects the content of the text field.
setSelectionRange(start: number, end: number, direction: 'forward' | 'backward' | 'none'): void

Selects a specific range in the text field.
setRangeText(replacement: string, start: number, end: number, selectMode: 'select' | 'start' | 'end' | 'preserve'): void

Replaces a specific range in the text field with new text.
checkValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event and returns false. If it's valid, it returns true.
reportValidity(): boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event, returns false, and displays a validation message. If it's valid, it returns true.
setCustomValidity(message: string): void

Sets a custom error message. If the text is non-empty, it indicates that the field is invalid.
click(): void

Simulates a mouse click on the element.
focus(options?: FocusOptions): void

Sets focus on the element. An optional parameter can be an object with a preventScroll property. If preventScroll is set to true, the page will not scroll to bring the focused element into view.
blur(): void

Removes focus from the element.
### Events
Name Description
focus

Emitted when the text field gains focus.
blur

Emitted when the text field loses focus.
change

Emitted when the value changes and the text field loses focus.
input

Emitted when the value changes.
invalid

Emitted when the form control's validity is checked and it doesn't meet the constraints.
clear

Emitted when clear button is clicked. Can be prevented with event.preventDefault().
### Slots
Name Description
icon

Icon on the left side.
end-icon

Icon on the right side.
error-icon

Icon on the right side for validation failure.
prefix

Text on the left side.
suffix

Text on the right side.
clear-button

Clear button.
clear-icon

Icon in the clear button.
toggle-password-button

Button to toggle password visibility.
show-password-icon

Icon in the password visibility toggle button (show password state).
hide-password-icon

Icon in the password visibility toggle button (hide password state).
helper

Text at the bottom for help.
### CSS Parts
Name Description
container

Container for the text field.
icon

Icon on the left side.
end-icon

Icon on the right side.
error-icon

Icon on the right side for validation failure.
prefix

Text on the left side.
suffix

Text on the right side.
label

Label text above the field.
input

Internal <input> or <textarea> element.
clear-button

Clear button.
clear-icon

Icon in the clear button.
toggle-password-button

Button to toggle password visibility.
show-password-icon

Icon in the password visibility toggle button (show password state).
hide-password-icon

Icon in the password visibility toggle button (hide password state).
supporting

Container for bottom supporting info, including helper, error, and counter.
helper

Text at the bottom for help.
error

Text at the bottom for error.
counter

Character count in the bottom right corner.
# Tooltip Component Tooltips provide supplementary text information for a specific element, enhancing the comprehension of its function or purpose. ## Usage {#usage} Import the component: ```js import 'mdui/components/tooltip.js'; ``` Import the TypeScript type: ```ts import type { Tooltip } from 'mdui/components/tooltip.js'; ``` Example: ```html button ``` ## Examples {#examples} ### Plain Text Tooltip {#example-plain} By default, the tooltip displays plain text. The `content` attribute specifies the tooltip content. ```html button ``` Alternatively, the `content` slot can also be used for this purpose. ```html button
title
content
 ``` ### Rich Text Tooltip {#example-rich} For a rich text tooltip, set the `variant` attribute to `rich`. The tooltip's title and content can be specified using the `headline` and `content` attributes, respectively. ```html button ``` Alternatively, the `headline` and `content` slots can be used to specify the tooltip's title and content. The `action` slot is used to specify the tooltip's action button. ```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 ``` ### Placement {#example-placement} The `placement` attribute sets the tooltip's position. ```html
``` ### Trigger Method {#example-trigger} The `trigger` attribute determines the trigger method for the tooltip. ```html button ``` ### Open/Close Delay {#example-delay} When the trigger method is `hover`, the `open-delay` and `close-delay` attributes set the opening and closing delays, respectively. The unit is in milliseconds. ```html button ``` ### Disabled State {#example-disabled} The `disabled` attribute disables the tooltip. ```html button ``` ## mdui-tooltip API ### Properties
Attribute Property Reflect Type Default Description
variant variant true 'plain' | 'rich' 'plain'

Defines the tooltip shape. Default is plain. Possible values:

  • plain: For simple single-line text.
  • rich: For text including a title, body text, and action buttons.
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'

Sets the tooltip position. Default is auto. Possible values:

  • auto: Position is determined automatically.
  • top-left: Top-left corner.
  • top-start: Top, left-aligned.
  • top: Top, centered.
  • top-end: Top, right-aligned.
  • top-right: Top-right corner.
  • bottom-left: Bottom-left corner.
  • bottom-start: Bottom, left-aligned.
  • bottom: Bottom, centered.
  • bottom-end: Bottom, right-aligned.
  • bottom-right: Bottom-right corner.
  • left-start: Left, top-aligned.
  • left: Left, centered.
  • left-end: Left, bottom-aligned.
  • right-start: Right, top-aligned.
  • right: Right, centered.
  • right-end: Right, bottom-aligned.
open-delay openDelay true number 150

Sets the delay in milliseconds before the tooltip appears on hover.
close-delay closeDelay true number 150

Sets the delay in milliseconds before the tooltip disappears on hover.
headline headline true string

Sets the tooltip title. Only applicable when variant="rich". Alternatively, use slot="headline".
content content true string

Sets the tooltip content. Alternatively, use slot="content".
trigger trigger true 'click' | 'hover' | 'focus' | 'manual' | string 'hover focus'

Defines the trigger method. Supports multiple values separated by spaces. Possible values:

  • click: Triggered on click.
  • hover: Triggered on mouse hover.
  • focus: Triggered on focus.
  • manual: Can only open and close the tooltip programmatically, cannot specify other trigger methods.
disabled disabled true boolean false

Disables the tooltip.
open open true boolean false

Opens the tooltip.
### Events
Name Description
open

Emitted when the tooltip starts to open. Can be prevented with event.preventDefault().
opened

Emitted after the tooltip has opened and the animations are completed.
close

Emitted when the tooltip starts to close. Can be prevented with event.preventDefault().
closed

Emitted after the tooltip has closed and the animations are completed.
### Slots
Name Description
(default)

Target element that triggers the tooltip. Only the first element in the default slot is used as the target.
headline

Title of the tooltip. Effective only when variant="rich".
content

Content of the tooltip, can contain HTML. If only plain text is included, can also use content attribute instead.
action

Button at the bottom of the tooltip. Effective only when variant="rich".
### CSS Parts
Name Description
popup

Container for the tooltip.
headline

Title of the tooltip.
content

Body text of the tooltip.
action

Action button of the tooltip.
### CSS Custom Properties
Name Description
--shape-corner-plain

Corner radius of the component when variant="plain". You can use a specific pixel value, but it's recommended to reference design tokens.
--shape-corner-rich

Corner radius of the component when variant="rich". You can use a specific pixel value, but it's recommended to reference design tokens.
--z-index

The CSS z-index value of the component.
# Top App Bar Component The Top App Bar provides information and actions related to the current screen, serving as a tool for branding, navigation, search, and actions. ## Usage {#usage} Import the component: ```js import 'mdui/components/top-app-bar.js'; import 'mdui/components/top-app-bar-title.js'; ``` Import the TypeScript type: ```ts import type { TopAppBar } from 'mdui/components/top-app-bar.js'; import type { TopAppBarTitle } from 'mdui/components/top-app-bar-title.js'; ``` Example: (Note: The `style="position: relative"` in the example is for demonstration purposes. Remove it in actual use.) ```html Title
``` **Notes:** By default, the top app bar uses `position: fixed` and automatically adds `padding-top` to the `body` to prevent the page content from being obscured. However, it uses `position: absolute` in the following cases: 1. When the `scroll-target` attribute is specified. In this case, `padding-top` is added to the element specified by `scroll-target`. 2. When it is within the [``](/en/docs/2/components/layout) component. In this case, `padding-top` is not added. ## Examples {#examples} ### In Container {#example-scroll-target} By default, the top app bar is positioned relative to the current window and appears at the top of the page. To place the top app bar inside a container, specify the `scroll-target` attribute on the `` component. Set its value to the CSS selector or DOM element of the container with scrollable content. In this case, the top app bar will be positioned relative to the parent element. Ensure to add the styles `position: relative; overflow: hidden` to the parent element. ```html
Title
``` ### Shape {#example-variant} The `variant` attribute on the `` component sets the shape of the top app bar. ```html
Title
center-aligned small medium large
``` ### Scroll Behavior {#example-scroll-behavior} The `scroll-behavior` attribute on the `` component defines the top app bar's behavior when the page is scrolled. You can use multiple scroll behaviors simultaneously by separating them with spaces. Scroll behaviors include: * `hide`: Hides the top app bar when scrolling down and shows it when scrolling up. * `shrink`: Effective when `variant` is `medium` or `large`. Expands the top app bar when scrolling down and shrinks it when scrolling up. * `elevate`: Adds a shadow to the top app bar when scrolling down and removes the shadow when scrolling back to the top. The `scroll-threshold` attribute sets the number of pixels to start the scroll behavior of the top app bar. (Do not set the `scroll-threshold` attribute when using the `elevate` scroll behavior to respond promptly) **Example: Hide on Scroll** ```html
Title
``` **Example: Add Shadow on Scroll** ```html
Title
``` **Example: Shrink on Scroll** ```html
Title
``` **Example: Shrink and Add Shadow on Scroll** ```html
Title
``` ### Expanded State Text {#label-large} For a top app bar with `variant` set to `medium` or `large`, and `scroll-behavior` set to `shrink`, you can use the `label-large` slot within the `` component to specify the text displayed in the expanded state. ```html
This is the collapsed state title This is the expanded state title
``` ## mdui-top-app-bar-title API ### Slots
Name Description
(default)

The title text of the top app bar.
label-large

The title text when the top app bar is in the expanded state.
### CSS Parts
Name Description
label

The title text.
label-large

The title text when the top app bar is in the expanded state.
## mdui-top-app-bar API ### Properties
Attribute Property Reflect Type Default Description
variant variant true 'center-aligned' | 'small' | 'medium' | 'large' 'small'

Defines the top app bar style. Default is small. Possible values:

  • center-aligned: Small app bar with a center-aligned title.
  • small: Small app bar.
  • medium: Medium-sized app bar.
  • large: Large-sized app bar.
hide hide true boolean false

Hide the top app bar.
shrink shrink true boolean false

Shrinks the app bar to small style. Only applicable for medium or large variants.
scroll-behavior scrollBehavior true 'hide' | 'shrink' | 'elevate'

Defines the scroll behavior. Accepts multiple space-separated values. Possible values:

  • hide: Hides when scrolling.
  • shrink: Shrinks when scrolling for medium to large app bars.
  • elevate: Increases elevation when scrolling.
scroll-target scrollTarget false string | HTMLElement | JQ<HTMLElement>

The element that listens for scroll events. Accepts a CSS selector, DOM element, or JQ object. Defaults to window.
scroll-threshold scrollThreshold true number

The scroll distance (in pixels) that triggers the scroll behavior.
order order true number

Specifies the layout order within the <mdui-layout> component. Items are sorted in ascending order. The default value is 0.
### Events
Name Description
show

Emitted when the top app bar starts to show. Can be prevented with event.preventDefault().
shown

Emitted after the top app bar has shown and animations are complete.
hide

Emitted when the top app bar starts to hide. Can be prevented with event.preventDefault().
hidden

Emitted after the top app bar has hidden and animations are complete.
### Slots
Name Description
(default)

Elements contained within the top app bar.
### CSS Custom Properties
Name Description
--shape-corner

The size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.
--z-index

The CSS z-index value of the component.
# JavaScript Library mdui includes a lightweight JavaScript utility library that provides a jQuery-like API with chainable calls, but at only a fraction of jQuery's size. Import the function: ```js import { $ } from 'mdui/jq.js'; ``` ## Core {#api-core} ### `$()` {#dollar} This function has several uses: Pass a CSS selector to get a JQ object containing the matching elements. ```js $('.box'); ``` Pass a DOM element, an array, a NodeList, or a JQ object to get a JQ object containing the specified elements. ```js $(document); ``` Pass an HTML string to create a JQ object containing the DOM elements created from the HTML. ```js $(`
`); ``` Pass a function to be called when the DOM is fully loaded. ```js $(function () { console.log('DOM Loaded') }); ``` ## Extension {#api-extend} ### `$.extend()` {#d-extend} Passing a single object merges its properties into the `$` object, effectively adding new functionality to the `$` namespace. ```js $.extend({ customFunc: function () {} }); // Now you can call the custom method like this $.customFunc(); ``` Passing two or more objects merges all properties from each object into the first one. The merged object is returned. Note that properties with a value of `undefined` are not merged. ```js const object = $.extend( { key1: val1 }, { key2: val2 }, { key3: val3 } ); // Both the first object and the returned value are now { key1: val1, key2: val2, key3: val3 } ``` ### `$.fn.extend()` {#fn-extend} This method extends the prototype chain of `$`, adding new methods. ```js $.fn.extend({ customFunc: function () {} }); // Now you can use the extended method like this $(document).customFunc(); ``` ## URL {#api-url} ### `$.param()` {#d-param} This method serializes an array or an object into a string that can be used as a URL query string. ```js $.param({ width: 1680, height: 1050 }); // Returns: "width=1680&height=1050" $.param({ foo: { one: 1, two: 2 } }); // Returns: "foo[one]=1&foo[two]=2" $.param({ ids: [1, 2, 3] }); // Returns: "ids[]=1&ids[]=2&ids[]=3" ``` If the parameter passed is an array, it should be in the format returned by the [`.serializeArray()`] method. ```js $.param([ { "name": "name", "value": "mdui" }, { "name": "password", "value": "123456" } ]); // Returns: "name=mdui&password=123456" ``` ## Array and Object Operations {#api-array} ### `$.each()` {#d-each} This method iterates over an array or object. It returns the first parameter, which is the array or object being traversed. The callback function's first parameter is the index for arrays or the key for objects. The second parameter is the value at the corresponding position. The `this` keyword in the callback function refers to the current value. If the callback function returns `false`, the iteration stops. ```js // Iterate over an array $.each(['a', 'b', 'c'], function (index, value) { console.log(index + ':' + value); }); // Result: // 0:a // 1:b // 2:c ``` ```js // Iterate over an object $.each({'name': 'mdui', 'lang': 'zh'}, function (key, value) { console.log(key + ':' + value); }); // Result: // name:mdui // lang:zh ``` ### `$.merge()` {#d-merge} This method appends the elements of the second array to the first array and returns the merged array. ```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} This method removes duplicate elements from an 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} This method iterates over an array or object, applying a function to each element, and returns a new array composed of the function's return values. The callback function's first parameter is the current element's value, and the second parameter is the index for arrays or the key for objects. The callback function can return any value. If it returns an array, the array will be flattened. If it returns `null` or `undefined`, the value will be ignored. The `this` keyword inside the function refers to the global window object. ```js // Iterate over an array const result = $.map(['a', 'b', 'c'], function (value, index) { return index + value; }); console.log(result); // ['0a', '1b', '2c'] ``` ```js // When the callback function returns an array, it will be flattened const result = $.map([1, 2, 3], function (value, index) { return [value, value + 1]; }); console.log(result); // [1, 2, 2, 3, 3, 4] ``` ```js // Iterate over an object const result = $.map({ name: 'mdui', password: '123456' }, function (value, key) { return key + ':' + value; }); console.log(result); // ['name:mdui', 'password:123456'] ``` ### `$.contains()` {#d-contains} This method checks if a parent node contains a child node, returning a boolean value. ```js $.contains(document, document.body); // true $.contains(document.body, document); // false ``` ## Data Type Checking {#api-type} ### `.is()` {#is} This method checks if at least one element in the collection matches the specified parameter. It returns a boolean value. The parameter can be a CSS selector, a DOM element, an array of DOM elements, a JQ object, or a function. When the parameter is a function, it takes the index and current element as arguments. `this` refers to the current element. The function should return `true` if the element matches, and `false` otherwise. ```js $('.box').is('.box'); // true $('.box').is('.boxss'); // false $('.box').is($('.box')[0]); // true ``` ```js // Using a function for comparison $(document).is(function (index, element) { return element === document; }); // true ``` ## Object Access {#api-object} ### `.length` {#length} This property returns the number of elements in the current collection. ```js $('body').length; // 1 ``` ### `.each()` {#each} This method iterates over the current collection, executing a function for each element. The iteration stops if the function returns `false`. The function's first parameter is the element's index, and the second is the current element. `this` refers to the current element. ```js $('img').each(function(index, element) { this.src = 'test' + index + '.jpg'; }); ``` ### `.map()` {#map} This method iterates over the current collection, executing a function for each element. It returns a new collection composed of the function's return values. The function can return a single value or an array. If it returns an array, the elements are added to the new collection. `null` or `undefined` returns are ignored. The function's first parameter is the element's index, and the second is the current element. `this` refers to the current element. ```js const result = $('input.checked').map(function (i, element) { return element.value; }); // result is a JQ object of values from matching elements ``` ### `.eq()` {#eq} This method returns a collection containing only the element at the specified index. ```js $('div').eq(0); // Returns a collection with the first div $('div').eq(-1); // Returns a collection with the last div $('div').eq(-2); // Returns a collection with the second-to-last div ``` ### `.first()` {#first} This method returns a collection containing only the first element of the current collection. ```js $('div').first(); // Returns a collection with the first div ``` ### `.last()` {#last} This method returns a collection containing only the last element of the current collection. ```js $('div').last(); // Returns a collection with the last div ``` ### `.get()` {#get} This method returns the element at the specified index. If no parameter is passed, it returns an array of all elements in the collection. ```js $('div').get(); // Returns an array of all div elements $('div').get(0); // Returns the first div element $('div').get(-1); // Returns the last div element ``` ### `.index()` {#index} This method returns the index of the first element in the current collection relative to its sibling elements if no parameter is passed. If a CSS selector is passed as a parameter, it returns the index relative to the elements matched by the selector. If a DOM element or a JQ object is passed as a parameter, it returns the index of that element within the current collection. ```html
``` ```js $('#child3').index(); // 2 $('#child3').index('#child div'); // 2 $('#child div').index($('#child3').get(0)); // 2 ``` ### `.slice()` {#slice} This method returns a subset of the current collection. The first parameter is the start position, and the second is the end position (exclusive). If the second parameter is omitted, the method includes all elements from the start position to the end of the collection. ```js $('div').slice(3); // Returns all elements from the third position onwards $('div').slice(3, 5); // Returns elements from the third to the fifth position (excluding the fifth) ``` ### `.filter()` {#filter} This method filters the current collection based on the specified criteria. The parameter can be a CSS selector, a DOM element, an array of DOM elements, or a callback function that returns a boolean. When the parameter is a callback, it takes the index of the element and the current element as arguments. `this` refers to the current element. If the function returns `true`, the element is included in the result; if `false`, it's excluded. ```js // Filters all div elements that contain the class .box $('div').filter('.box'); // Filters all selected options $('#select option').filter(function (index, element) { return element.selected; }); ``` ### `.not()` {#not} This method excludes elements from the current collection that match the specified criteria. The parameter can be a CSS selector, a DOM element, an array of DOM elements, a JQ object, or a callback function returning a boolean. When the parameter is a callback, the function's first parameter is the index of the element, the second is the current element, and `this` refers to the current element. If the function returns `true`, the element is excluded; if `false`, it's included. ```js // Exclude all div elements that contain the class .box $('div').not('.box'); // Exclude all unselected options $('#select option').not(function (index, element) { return element.selected; }); ``` ## CSS Classes {#api-css} ### `.hasClass()` {#hasClass} This method checks if the first element in the collection has the specified CSS class. ```js // Returns true if the first div has the class .item $('div').hasClass('item'); ``` ### `.addClass()` {#addClass} This method adds CSS classes to each element in the collection. You can add multiple class names by separating them with spaces. The parameter can be a string or a callback function that returns a CSS class name. The callback function's first parameter is the element's index, the second is the existing CSS class name, and `this` refers to the current element. ```js // Adds .item to all div elements $('div').addClass('item'); // Adds .item1 and .item2 to all div elements $('div').addClass('item1 item2'); // Adds CSS classes returned by the callback function to all div elements $('div').addClass(function (index, currentClassName) { return currentClassName + '-' + index; }); ``` ### `.removeClass()` {#removeClass} This method removes specified CSS classes from each element in the collection. You can remove multiple class names by separating them with spaces. The parameter can be a string or a callback function that returns a CSS class name. The callback function's first parameter is the element's index, the second is the existing CSS class name, and `this` refers to the current element. If no parameter is passed, it will remove the `class` attribute from the elements. ```js // Removes .item from all div elements $('div').removeClass('item'); // Removes .item1 and .item2 from all div elements $('div').removeClass('item1 item2'); // Removes CSS classes returned by the callback function from all div elements $('div').removeClass(function (index, currentClassName) { return 'item'; }); ``` ### `.toggleClass()` {#toggleClass} This method toggles CSS classes for each element in the collection. If a class exists, it's removed; if it doesn't exist, it's added. You can toggle multiple class names by separating them with spaces. The parameter can be a string or a callback function that returns a CSS class name. The callback function's first parameter is the element's index, the second is the existing CSS class name, and `this` refers to the current element. ```js // Toggles .item on all div elements $('div').toggleClass('item'); // Toggles .item1 and .item2 on all div elements $('div').toggleClass('item1 item2'); // Toggles CSS classes returned by the callback function on all div elements $('div').toggleClass(function (index, currentClassName) { return 'item'; }); ``` ## Element Properties {#api-attr} ### `.prop()` {#prop} This method retrieves the JavaScript property value of the first element in the collection. ```js // Get the 'checked' property value of the first input element $('input').prop('checked'); ``` This method can also set JavaScript property values for all elements in the collection. The property value can be any type, or the return value of a callback function. The callback function's first parameter is the element's index, the second is the existing property value, and `this` refers to the current element. If the property value or the callback function's return value is `undefined`, the original property remains unchanged. ```js // Set the 'checked' property to true for all input elements $('input').prop('checked', true); // Toggle the 'checked' property for all input elements $('input').prop('checked', function (index, oldPropValue) { return true; }); ``` You can also set multiple properties at once by passing an object. ```js // Set multiple property values for the elements $('input').prop({ checked: false, disabled: function (index, oldPropValue) { return true; } }); ``` ### `.removeProp()` {#removeProp} This method removes the specified JavaScript property from all elements in the collection. ```js $('input').removeProp('disabled'); ``` ### `.attr()` {#attr} This method retrieves the HTML attribute value of the first element in the collection. ```js // Get the 'username' attribute value of the first div element $('div').attr('username'); ``` This method can also set HTML attribute values for all elements in the collection. The attribute value can be a string, a number, or the return value of a callback function. The callback function's first parameter is the element's index, the second is the existing attribute value, and `this` refers to the current element. If the attribute value or the callback function's return value is `null`, the specified attribute will be removed. If it's `undefined`, the original attribute remains unchanged. ```js // Set the 'username' attribute to 'mdui' for all div elements $('div').attr('username', 'mdui'); // Set the 'username' attribute to 'mdui' for all div elements $('div').attr('username', function (index, oldAttrValue) { return 'mdui'; }); ``` You can also set multiple attributes at once by passing an object. ```js // Set multiple attribute values for all div elements $('div').attr({ username: 'mdui', lastname: function (index, oldAttrValue) { return 'test'; } }); ``` ### `.removeAttr()` {#removeAttr} This method removes specified attributes from all elements in the collection. Multiple attribute names can be separated by spaces. ```js // Remove 'username' attribute from all div elements $('div').removeAttr('username'); // Remove 'username' and 'lastname' attributes from all div elements $('div').removeAttr('username lastname'); ``` ### `.val()` {#val} This method retrieves the value of the first element in the collection. For a ``, ``, ``, or `