mingcute-icons README

The project's README from github.com/mingcute-design/mingcute-icons. As one markdown file: README.md.

Mingcute Icons in Core Regular and Core Filled styles

Mingcute Icons

Carefully Designed Icon Library

Mingcute website  @mingcute/icons npm version  @mingcute/icons minified and gzipped package size  Monthly @mingcute/icons downloads  Mingcute Icons GitHub stars

Overview

Mingcute Icons is the public, open-source distribution of the Mingcute Icon System.

It provides 1,663 icons in both Core Regular and Core Filled, for a total of 3,326 styled icon definitions, distributed across 10 production packages for:

Every renderer uses the same generated @mingcute/icons definitions. Icon geometry is compiled once rather than duplicated across framework packages, keeping rendering consistent and the repository easier to maintain.

Highlights

Mingcute icons used in production interfaces

Design Foundation

Every Mingcute icon is drawn on a 24 × 24 grid with consistent visual proportions.

The public catalogue includes:

Core Regular is designed around a consistent 2 px stroke. Canonical vector artwork remains editable in the source files and scales through SVG without losing its intended proportions.

Use the Mingcute website to:

Use the packages in this repository when icons need to be installed, versioned, tree-shaken, and rendered consistently in an application.

Editable Mingcute vector construction

Quick Start

1. Install the package for your framework

For React:

npm install @mingcute/react

For another framework, replace @mingcute/react with the appropriate package listed below.

2. Import an icon

import { Home1Regular } from '@mingcute/react/core-regular';

export function HomeLink() {
  return (
    <a href="/">
      <Home1Regular size={20} aria-hidden="true" />
      <span>Home</span>
    </a>
  );
}

Packages

Install only the package required by your project.

Target Package Installation Purpose
Icon definitions @mingcute/icons npm install @mingcute/icons Framework-neutral definitions and rendering helpers
React @mingcute/react npm install @mingcute/react Typed React SVG components
Vue @mingcute/vue npm install @mingcute/vue Typed Vue 3 SVG components
React Native @mingcute/react-native npm install @mingcute/react-native Native components using react-native-svg
Svelte @mingcute/svelte npm install @mingcute/svelte Svelte 5 icon components
SolidJS @mingcute/solid npm install @mingcute/solid SolidJS icon components
Vanilla JavaScript @mingcute/vanilla npm install @mingcute/vanilla SVG strings and DOM helpers
Web Components @mingcute/web-components npm install @mingcute/web-components Explicitly registered custom elements
SVG @mingcute/svg npm install @mingcute/svg Optimized standalone SVG files
Font @mingcute/font npm install @mingcute/font WOFF2 fonts, CSS classes, and metadata

Framework packages use @mingcute/icons for shared icon geometry. The definitions package is installed automatically when required.

Package-manager examples

# npm
npm install @mingcute/react

# pnpm
pnpm add @mingcute/react

# Yarn
yarn add @mingcute/react

# Bun
bun add @mingcute/react

Available Styles

The public release contains 3,326 styled icon definitions across two importable styles.

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

Additional Core, Cute, and Sharp styles are available in Mingcute Pro.

Free and Pro

Capability Mingcute Icons Mingcute Pro
Families and styles Core Regular and Core Filled 12 Core, Cute, and Sharp style combinations
Styled definitions 3,326 20,152
Package names @mingcute/* @mingcute/*-pro
Distribution Public npm registry Private Mingcute registry
Access No account or CLI required Active Pro entitlement and CLI configuration
License Apache-2.0 Mingcute Pro Commercial License

The public and Pro packages use the same framework conventions and import structure. This makes migration straightforward while keeping the source repositories and licensing boundaries separate.

Usage

React

import { Home1Regular } from '@mingcute/react/core-regular';

export function HomeIcon() {
  return <Home1Regular size={24} title="Home" />;
}

Vue

<script setup lang="ts">
import { Home1Filled } from '@mingcute/vue/core-filled';
</script>

<template>
  <Home1Filled :size="24" title="Home" />
</template>

React Native

import { Home1Regular } from '@mingcute/react-native/core-regular';

export function HomeIcon() {
  return <Home1Regular size={24} color="#10161F" title="Home" />;
}

React Native requires react-native-svg 13 or newer.

Svelte

<script>
  import { Home1Regular } from '@mingcute/svelte/core-regular';
</script>

<Home1Regular size={24} title="Home" />

SolidJS

import { Home1Regular } from '@mingcute/solid/core-regular';

export function HomeIcon() {
  return <Home1Regular size={24} title="Home" />;
}

Vanilla JavaScript

import { createIcon } from '@mingcute/vanilla';
import { Home1Regular } from '@mingcute/vanilla/core-regular';

const navigation = document.querySelector('nav');

navigation?.append(
  createIcon(Home1Regular, {
    size: 24,
    title: 'Home',
  }),
);

Web Components

Register the component:

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

defineHome1Regular();

Use the registered custom element:

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

Standalone SVG

import homeUrl from '@mingcute/svg/core-regular/home-1.svg';

Icon Font

Import the stylesheet:

import '@mingcute/font/core-regular.min.css';

Use the generated class:

<i class="mgc mgc-home-1-regular" aria-hidden="true"></i>

Framework-Neutral Definitions

import { renderIconSource } from '@mingcute/icons';
import { Home1Icon } from '@mingcute/icons/core-regular';

const svg = renderIconSource(Home1Icon);

Package Model

@mingcute/icons contains the framework-neutral icon definitions.

Framework packages provide small renderer-specific wrappers and install the shared definitions automatically:

@mingcute/icons
├── @mingcute/react
├── @mingcute/vue
├── @mingcute/react-native
├── @mingcute/svelte
├── @mingcute/solid
├── @mingcute/vanilla
└── @mingcute/web-components

This structure prevents icon geometry from being duplicated across framework packages.

The standalone SVG and font packages are generated from the same canonical artwork and validated independently.

Import Strategy

Style entry points

Use a style entry point for convenient named imports:

import {
  Home1Regular,
  Search2Regular,
} from '@mingcute/react/core-regular';

Direct icon imports

Use a direct icon path for the smallest module graph:

import Home1Regular from '@mingcute/react/core-regular/home-1';

Package roots expose shared utilities and types rather than the complete icon catalogue. This prevents accidental imports of every icon.

Performance and Module Format

Mingcute JavaScript packages:

JavaScript packages declare sideEffects: false.

@mingcute/font marks imported CSS as side-effectful so bundlers retain the stylesheet.

For predictable bundle sizes:

Accessibility

Framework components are decorative by default and remain hidden from assistive technology unless they receive an accessible title or label.

The examples below use these React imports:

import {
  Home1Regular,
  MenuRegular,
} from '@mingcute/react/core-regular';

Meaningful icons

Provide a title when an icon communicates meaning by itself:

<Home1Regular size={24} title="Home" />

Decorative icons

Keep decorative icons hidden from assistive technology:

<Home1Regular size={24} aria-hidden="true" />

Icons inside labelled controls

When visible text already labels a button or link, the icon should normally remain decorative:

<button type="button">
  <Home1Regular size={20} aria-hidden="true" />
  <span>Home</span>
</button>

Icon-only controls

Give the control an accessible name and keep the icon decorative:

<button type="button" aria-label="Open navigation">
  <MenuRegular size={20} aria-hidden="true" />
</button>

Do not rely on an icon’s shape or color alone to communicate an action, status, or meaning.

Rendering

The compiler preserves supported SVG features, including:

Resource identifiers are scoped per rendered instance to prevent collisions when the same icon appears more than once on a page.

Icon fonts cannot reproduce every SVG feature. Use the SVG or framework packages when exact gradients, masks, patterns, or original colors are required.

Compatibility

Package Supported runtime
@mingcute/react React 18 or 19
@mingcute/vue Vue 3.5 or newer
@mingcute/react-native React 18+, React Native 0.72+, and react-native-svg 13+
@mingcute/svelte Svelte 5.20 or newer
@mingcute/solid SolidJS 1.9.x
Vanilla, Web Components, and SVG Modern ESM toolchains and standards-compliant SVG environments
Font Modern browsers with WOFF2 support

Repository development requires:

Consumer applications do not need pnpm unless they are contributing to this repository.

Troubleshooting

An icon import cannot be resolved

Confirm:

Component exports use PascalCase with a style suffix:

Home1Regular

Direct icon filenames use kebab-case:

home-1

The production bundle is larger than expected

Use a direct icon import:

import Home1Regular from '@mingcute/react/core-regular/home-1';

Confirm that your bundler supports ESM tree shaking and avoid namespace imports of complete style entry points.

An icon is announced twice

Keep the icon decorative when nearby text already labels the action:

<button type="button">
  <Home1Regular aria-hidden="true" />
  <span>Home</span>
</button>

Only add a title or accessible label when the icon communicates meaning by itself.

A gradient or brand icon differs in another format

Use the SVG or framework component package for maximum fidelity.

Icon fonts cannot reproduce every gradient, mask, pattern, or original-color asset.

Source and Generation

Canonical SVG artwork is stored using the following structure:

assets/svg/core/{regular,filled}/{category}/{icon}.svg

The source directories organize canonical artwork. Consumer packages flatten each style into stable package subpaths:

@mingcute/react/core-regular
@mingcute/svg/core-regular/home-1.svg

Because the style is already represented by the package subpath, generated files use concise names such as:

home-1.svg

The compiler:

  1. parses canonical SVG artwork;
  2. optimizes its structure;
  3. normalizes supported geometry and paint;
  4. validates rendering constraints; and
  5. passes the result to package-specific generators.

Generated package output should not be edited by hand.

Repository Structure

mingcute-icons/
├── assets/
│   └── svg/core/{regular,filled}/
├── packages/
│   ├── core/                       private build contracts
│   ├── compiler/                   private SVG compiler
│   ├── icons/                      @mingcute/icons
│   ├── react/                      @mingcute/react
│   ├── vue/                        @mingcute/vue
│   ├── react-native/               @mingcute/react-native
│   ├── svelte/                     @mingcute/svelte
│   ├── solid/                      @mingcute/solid
│   ├── vanilla/                    @mingcute/vanilla
│   ├── web-components/             @mingcute/web-components
│   ├── svg/                        @mingcute/svg
│   └── font/                       @mingcute/font
├── release.json                    coordinated public package version
└── pnpm-workspace.yaml

@mingcute/core and @mingcute/compiler are private workspace packages. They are never published and must not appear in consumer runtime dependency trees.

Development

Prerequisites

Install and validate

pnpm install --frozen-lockfile
pnpm build
pnpm check
pnpm release:check
pnpm pack:dry

pnpm release:check verifies:

Contributing

  1. Use Node.js 22 or newer and pnpm 9.15.0.
  2. Change canonical source or the owning generator instead of editing generated package output.
  3. Add focused tests for changes to compilation, rendering, exports, types, or accessibility.
  4. Run pnpm check and pnpm pack:dry before opening a pull request.
  5. Keep Pro artwork, commercial license material, registry configuration, credentials, and private delivery code out of this repository.

Bug reports should include:

Release Policy

All 10 public packages use the coordinated version defined in release.json.

A release is complete only when every package passes:

Avoid documenting a fixed release version in this README. The current version should be read from package metadata or release.json.

Figma Plugin and Resources

Mingcute Icon Figma plugin

Install the Mingcute Icon Figma plugin to search and place icons directly in Figma.

Related resources:

Security and Support

Do not report suspected vulnerabilities in a public issue.

Contact the Mingcute team privately through the Mingcute website and include the affected versions and reproduction details.

For package usage or rendering defects, include:

mingcute-icons (mingcute-design/mingcute-icons)

Searching Database…

1.7K ·GitHub
Mingcute-icons
What is this?MingCute Icons is an open-source icon library with 1,663 icons in Core Regular and Core Filled styles (3,326 total definitions), distributed as packages for React, Vue, React Native, Svelte, SolidJS, vanilla JS, web components, SVG, and WOFF2 fonts.
Is this a single icon font, or a set of packages per framework?It's a framework-neutral icon definitions package (@mingcute/icons) plus thin typed wrapper packages for each target (React, Vue, Svelte, SolidJS, React Native, web components, vanilla JS, SVG files, and a WOFF2 font) that all share the same generated geometry.
How do I add icons to my project?Install only the package for your framework, e.g. 'npm install @mingcute/react' for React, then import a specific icon component or SVG path; other frameworks use the matching @mingcute/ package (vue, react-native, svelte, solid, vanilla, web-components, svg, font).
Does React Native need anything extra?Yes, React Native support requires react-native-svg version 13 or newer in addition to @mingcute/react-native.
Does this free version include every icon style?No, the free public release only has Core Regular and Core Filled (3,326 definitions); additional Core, Cute, and Sharp styles with 20,152 definitions require Mingcute Pro, a separate commercial-licensed product with its own private registry.
Why is there a separate @mingcute/icons package instead of putting icons straight into each framework package?The icon geometry is compiled once into @mingcute/icons and every framework adapter (React, Vue, etc.) just consumes those shared definitions, so icon artwork is never duplicated or allowed to drift between packages.
How do icons behave with screen readers by default?Framework icon components are decorative by default and stay hidden from assistive technology unless you explicitly give them an accessible title or label, so icon-only buttons need an explicit accessible name.
Can I browse and tweak icons without installing a package?Yes, the Mingcute website lets you search the catalogue, preview icons, adjust size and color, and download individual SVG or PNG files without any install; there is also a Figma plugin to place icons directly in Figma.
How do I keep my bundle small when importing icons?Use direct icon path imports instead of namespace imports from a style entry point, since packages are ESM-only, tree-shakeable, and declare sideEffects: false, letting bundlers drop unused icons.
What are similar projects?tabler-icons, simple-icons, heroicons, storybook, lucide, loadersz-core, blobatar, react-native-ui-kitten
Which topics is it in?icon-font, iconset, icon-pack, web-components, icons, svelte, react-native, svg, accessibility, design, vue, react
Creator
mingcute-design
Size
30.5 MB
Stars
1.7K
Updated
CommitJul 31Releasev3.0.2Jul 31
Age
5y
Commits · 90 Days