Mingcute Icons

@mingcute/core is a private workspace package used to define shared architecture contracts for the Mingcute Icons repository.

CRITICAL: This package is not an npm product and must never be installed by consumer applications.

It centralizes the following internal logic:

• Public style declarations: The canonical style catalogue.
• Icon and metadata contracts: Normalized models for names, components, and geometry.
• Naming rules: Rules for files, exports, and components.
• Adapter build contracts: Stable contracts for framework generators.
• Deterministic helpers: Shared utilities for generators and tests.

If you are building an application using Mingcute icons, you should depend on @mingcute/icons or specific framework packages (like @mingcute/react) instead of @mingcute/core.

Each icon module exports a custom-element constructor, a define...() registration function, and the icon's default tag name.

Registration is idempotent and side-effect free. The define...() function accepts an optional name (to alias the tag) and an optional registry (for isolated environments or testing).

Registration API:

• defineIconElement(tagName, constructor, registry?): A lower-level helper for manual registration.
• define[IconName](): The standard registration function exported by icon modules.

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

// Standard registration
defineHome1Regular();

// Custom tag name registration
defineHome1Regular('my-custom-home-icon');

Mingcute icons follow accessibility best practices. Icons without a title or explicit accessible name are hidden from assistive technology by default.

• Meaningful icons: Provide a title prop when the icon communicates meaning independently.
• Decorative icons: Leave the icon without a title if nearby text already labels the action.
• Icon-only controls: When using an icon inside an interactive control (like a button), put the accessible name on the control itself and keep the icon decorative.

An IconDefinition is a structured, typed representation of an icon. Instead of raw SVG strings, it stores icon data as a set of properties including:

• view-box information
• normalized shape nodes
• fills and strokes
• groups and transforms
• gradients, masks, clip paths, and patterns
• self-contained embedded images
• generated metadata

This structured approach allows framework adapters (like @mingcute/react or @mingcute/vue) to render icons efficiently and safely. When building a custom renderer, you should account for all these node types to ensure no artwork is lost.

Icon fonts cannot reproduce every SVG feature. If your design requires exact gradients, masks, patterns, or original colors, do not use the Font package. Instead, use the SVG or framework-specific component packages (e.g., @mingcute/react, @mingcute/vue) to ensure full support for:

• Standard SVG geometry
• Gradients
• Masks
• Clipping paths
• Self-contained image patterns

Mingcute icons are designed to be accessible by default. Unlabeled icons are hidden from assistive technology.

• Meaningful icons: If an icon communicates meaning by itself, provide a title prop or a platform-appropriate accessibility label.
• Decorative icons: If an icon is next to text that already labels the action, keep the icon decorative (do not provide a title).
• Icon-only controls: When using an icon inside an interactive element (like a button), place the accessible name on the control itself and keep the icon decorative.

When using icons, follow these patterns to ensure accessibility:

Meaningful icons

If the icon conveys meaning, provide one clear accessible name using the title option:

toSvgString(Home1Regular, {
  size: 24,
  title: 'Home',
});

Decorative icons

If the icon is purely decorative (e.g., next to text that already provides the label), hide it from assistive technologies using ariaHidden: true:

createIcon(Home1Regular, {
  size: 20,
  ariaHidden: true,
});

Icon-only controls

If the icon is inside a button or control, place the accessible name on the control element itself rather than duplicating it on the SVG.

You can style the custom element host directly using attributes like size and color.

To style the internal SVG, you must use the ::part(svg) CSS selector, as ordinary descendant selectors cannot cross the Shadow DOM boundary. The SVG is also accessible via the element.svg property in JavaScript.

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

/* Styling the internal SVG */
.app-icon::part(svg) {
  display: block;
}

Use the following commands to build, typecheck, test, and audit the compiler within the workspace:

pnpm --filter @mingcute/compiler build
pnpm --filter @mingcute/compiler typecheck
pnpm --filter @mingcute/compiler test
pnpm --filter @mingcute/compiler audit:assets

After making changes to the compiler, you must run repository-wide validation to ensure no regressions were introduced across the entire icon system:

pnpm build
pnpm check
pnpm release:check
pnpm pack:dry

To ensure the smallest possible bundle size and avoid Metro module graph bloat, follow these production guidelines:

1. Use direct icon subpaths: Instead of importing from style entry points, use paths like @mingcute/react-native/core-regular/home-1.
2. Avoid namespace imports: Do not use import * as Icons from ... as this prevents tree-shaking.
3. ESM usage: The package is ESM-only and side-effect free; ensure your bundler is configured to tree-shake ESM effectively.

You can install the @mingcute/icons package using any of the following package managers:

# npm
npm install @mingcute/icons

# pnpm
pnpm add @mingcute/icons

# Yarn
yarn add @mingcute/icons

# Bun
bun add @mingcute/icons

Install the Mingcute Vue adapter using your preferred package manager. Note that Vue 3.5 or newer is required.

# npm
npm install @mingcute/vue

# pnpm
pnpm add @mingcute/vue

# Yarn
yarn add @mingcute/vue

# Bun
bun add @mingcute/vue