DOCSEARCHbyAlgolia
Submit Docs

mdui Documentation

repository·v2·Indexed 26 days ago

https://github.com/zdhxiong/mdui

A framework-agnostic Material Design 3 (Material You) library of Web Components. mdui supports dark themes, dynamic colors, and is written in TypeScript with zero dependencies. The ecosystem includes @mdui/icons for SVG icons, @mdui/jq for a lightweight JavaScript utility library, and @mdui/mcp for an MCP server providing AI agents with component metadata, CSS tokens, and documentation. Developer tools are available via VSCode and IntelliJ IDE plugins.

Tokens
76.2K
Snippets
234
Records
431
Agent score
86%

What's inside mdui

  1. Overview of mdui features

    v2

    mdui is a lightweight (85KB gzipped) Web Component library following the Material Design 3 (Material You) specification.

    Key features include:

    • Web Components: Easy to use like standard HTML tags.
    • Material You: Follows the latest design specs.
    • Dynamic Color: Automatically generates color schemes from a color value or an image.
    • Dark Mode: Supports dark mode and automatic switching based on OS settings.
    • Framework Agnostic: Compatible with Vue, React, Angular, and any environment running in a browser.
    • Zero Dependencies: No third-party library requirements.
    • TypeScript Support: Fully written in TypeScript for excellent type hinting.

  3. Overview of @mdui/mcp

    v2
    @mdui/mcp is an MCP (Model Context Protocol) server designed for AI agents and IDEs. It provides read-only, offline, and deterministic tools to discover mdui components, icons, CSS tokens, and documentation, allowing agents to query structured data reliably.

  4. Use mdui Autocompletion and Hover Tooltips

    v2

    The plugin provides intelligent autocompletion and hover information in the following scenarios:

    HTML Context:

    • HTML tag names
    • HTML attribute names
    • HTML attribute enumerated values
    • Event names within HTML tags

    CSS Context:

    • part attribute names within ::part() selectors
    • CSS custom property names inside components
    • Global CSS custom property names
    • Global CSS class names

  5. Manipulate mdui component attributes and properties

    v2

    mdui components are Web Components. You can interact with them using both HTML attributes and JavaScript properties.

    • HTML Attributes: Set directly in HTML or via setAttribute()/getAttribute().
    • JavaScript Properties: Accessed directly on the element instance.
    • Synchronization: Most attributes and properties are synchronized. Updating one updates the other.
    • Boolean Attributes: For boolean properties (like disabled), the presence of the attribute sets it to true. To set it to false via attribute, use the string 'false'.
    • Complex Properties: Properties that are arrays, objects, or functions (e.g., labelFormatter on <mdui-slider>) can only be set via JavaScript properties.
    <mdui-button variant="text">Click me</mdui-button>

<script>
  const button = document.querySelector('mdui-button');

  // Using HTML attributes
  button.setAttribute('variant', 'outlined');
  console.log(button.getAttribute('variant')); // "outlined"

  // Using JavaScript properties
  button.variant = 'outlined';
  console.log(button.variant); // "outlined"

  // Boolean attribute exception: setting to string "false" works for compatibility
  button.setAttribute('disabled', 'false'); 

  // Complex properties (functions/objects) must use JS properties
  const slider = document.querySelector('mdui-slider');
  slider.labelFormatter = (value) => `${value}%`;
</script>

  6. Use the Card component

    v2

    The mdui-card component is a versatile container for content and actions. To use it, import the component module in your JavaScript file. If you are using TypeScript, you can also import the Card type.

    import 'mdui/components/card.js';
    import type { Card } from 'mdui/components/card.js';
    <mdui-card style="width: 200px;height: 124px">Card Content</mdui-card>

  7. Customize Typography with Design Tokens

    v2

    mdui provides 15 typography styles. Each style is composed of four CSS custom properties: line-height, size, tracking (letter-spacing), and weight.

    You can override these properties globally in :root to change the look of a specific type scale (e.g., Body large) across your entire application, or apply them to specific elements.

    Example of overriding and applying a style:

    /* Modify the text style of Body large globally */
: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;
}

/* Apply the Body large style to an element */
.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);
}
    /* Example of applying typography tokens */
.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);
}

  8. Import Top App Bar components

    v2

    To use the Top App Bar in your project, import the component JavaScript files. If you are using TypeScript, you can also import the specific types for TopAppBar and TopAppBarTitle.

    import 'mdui/components/top-app-bar.js';
import 'mdui/components/top-app-bar-title.js';
    import type { TopAppBar } from 'mdui/components/top-app-bar.js';
import type { TopAppBarTitle } from 'mdui/components/top-app-bar-title.js';

  9. Import List components

    v2

    To use the List component, its items, and subheaders, import the corresponding JavaScript modules. If you are using TypeScript, you can also import the specific types.

    import 'mdui/components/list.js';
import 'mdui/components/list-item.js';
import 'mdui/components/list-subheader.js';
    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';
    import 'mdui/components/list.js';
import 'mdui/components/list-item.js';
import 'mdui/components/list-subheader.js';

  11. Import Segmented Button components

    v2

    To use the Segmented Button components, import the JavaScript modules for the group and the individual buttons. If you are using TypeScript, you can also import the corresponding types.

    import 'mdui/components/segmented-button-group.js';
import 'mdui/components/segmented-button.js';
    import type { SegmentedButtonGroup } from 'mdui/components/segmented-button-group.js';
import type { SegmentedButton } from 'mdui/components/segmented-button.js';

  12. Make a Card clickable or a link

    v2

    You can make a card interactive using the following attributes:

    • clickable: Adds hover and click ripple effects.
    • href: Turns the card into a link. When using href, standard link attributes like download, target, and rel are also supported.