Overview

@mingcute/web-components provides one custom-element class and one registration function for every public Mingcute icon.

Importing an icon module does not modify the global custom-element registry. Registration is explicit, idempotent, and controlled by the application.

Highlights

• Explicit registration: imports remain side-effect free.
• Tree-shakeable modules: import only the icons your application registers.
• Standards-based rendering: Custom Elements, Shadow DOM, and SVG.
• Accessible defaults: unlabeled icons remain decorative.
• Style isolation: the internal SVG is exposed through part="svg".
• Shared icon geometry: generated elements consume @mingcute/icons.

Installation

# npm
npm install @mingcute/web-components

# pnpm
pnpm add @mingcute/web-components

# Yarn
yarn add @mingcute/web-components

# Bun
bun add @mingcute/web-components

Quick Start

Register the icon in browser startup code:

import { defineHome1Regular } from '@mingcute/web-components/core-regular/home-1';

defineHome1Regular();

Then use the custom element:

<mingcute-home-1-regular
  size="24"
  title="Home"
></mingcute-home-1-regular>

Importing the module alone does not register the element.

Registration API

Each icon module exports:

• a generated custom-element constructor;
• a define...() registration function; and
• the icon’s default tag name.

import {
  Home1RegularElement,
  defineHome1Regular,
} from '@mingcute/web-components/core-regular/home-1';

The generated function accepts an optional tag name and registry:

defineHome1Regular(name?, registry?);

It registers the icon and returns its constructor.

The lower-level helper supports tests and isolated registries:

defineIconElement(tagName, constructor, registry?);

Registration:

• validates custom-element names;
• does not replace an existing tag with a different constructor;
• safely returns the existing constructor when registration is repeated; and
• supports an explicit registry when the environment provides one.

API Reference

| Attribute | Default | Purpose | |---|---|---| | size | 24 | Sets width and height unless either dimension is provided | | width | size | Overrides the SVG width | | height | size | Overrides the SVG height | | color | currentColor | Sets the inherited SVG paint color | | title | none | Adds an accessible <title> | | title-id | generated | Overrides the title association ID | | aria-label | none | Provides an accessible name | | aria-labelledby | none | Associates external accessible text | | aria-hidden | accessibility default | Overrides assistive-technology visibility | | role | accessibility default | Overrides the generated role | | class, style | none | Styles the custom-element host |

The rendered SVG is available through:

element.svg

It is also exposed as a CSS shadow part:

mingcute-home-1-regular::part(svg) {
  display: block;
}

Styling

Set supported values directly on the host:

<mingcute-home-1-regular
  size="20"
  color="rebeccapurple"
></mingcute-home-1-regular>

Use ::part(svg) to style the internal SVG:

.app-icon::part(svg) {
  display: block;
}

Ordinary descendant selectors cannot cross the Shadow DOM boundary.

Accessibility

Unlabeled elements render as decorative.

Meaningful icons

Provide a title or ARIA label when the icon communicates meaning by itself:

<mingcute-home-1-regular
  size="24"
  title="Home"
></mingcute-home-1-regular>

Decorative icons

Keep the icon decorative when visible text already provides the label:

<button type="button">
  <mingcute-home-1-regular
    size="20"
    aria-hidden="true"
  ></mingcute-home-1-regular>
  <span>Home</span>
</button>

Icon-only controls

Place the accessible name on the control:

import { defineMenuRegular } from '@mingcute/web-components/core-regular/menu';

defineMenuRegular();

<button type="button" aria-label="Open navigation">
  <mingcute-menu-regular
    size="20"
    aria-hidden="true"
  ></mingcute-menu-regular>
</button>

Browser and Server Environments

Custom elements require browser support for:

• Custom Elements;
• Shadow DOM; and
• standards-compliant SVG.

Icon modules can be imported in server code, but registration must be deferred until a custom-element registry is available.

if (typeof customElements !== 'undefined') {
  defineHome1Regular();
}

Available Styles

| Import subpath | Style | Icons | |---|---|---:| | core-regular | Core Regular | 1,663 | | core-filled | Core Filled | 1,663 | | Total | All public styles | 3,326 |

Production Guidance

• The package is ESM-only and side-effect free.
• Importing an icon does not register it.
• Register icons during browser startup or feature initialization.
• Prefer direct icon imports to keep registrations and module graphs explicit.
• Use unique tag names for application-specific aliases.
• Style the internal SVG through ::part(svg).
• Avoid registering the same tag with different constructors.

Integration with Definitions

Generated custom elements consume canonical geometry from @mingcute/icons.

@mingcute/icons owns icon data and metadata.

@mingcute/web-components owns:

• custom-element classes;
• explicit registration;
• Shadow DOM rendering;
• host attributes;
• SVG part exposure; and
• accessibility behavior.

Troubleshooting

The custom-element tag renders nothing

Confirm that its registration function ran after customElements became available:

defineHome1Regular();

Registration throws an error

The tag may already be registered with another constructor. Use a unique custom-element name or reuse the existing definition.

CSS does not reach the SVG

Use the exposed shadow part:

mingcute-home-1-regular::part(svg) {
  display: block;
}

Server rendering fails during registration

Import the module on the server if needed, but call define...() only in the browser.

The bundle is larger than expected

Use direct icon modules and register only the icons required by the application.

Development

This package is generated from canonical SVG sources. Do not edit generated output by hand.

pnpm --filter @mingcute/web-components check

License

Licensed under the Apache License 2.0.

Links

• Mingcute website
• Package changelog
• Mingcute Icons packages
• Repository