Getting started
Install Master Icons and render your first icon.
On this page
#Install
Install the package for your framework. Each framework package brings the shared @master/icons core with it and uses the framework already in your application.
| Framework | Package |
|---|---|
| React 18 or 19 | @master/icons-react |
| Vue 3.5 or later | @master/icons-vue |
| Svelte 5 | @master/icons-svelte |
| Preact 11 | @master/icons-preact |
| Astro 7 | @master/icons-astro |
| No framework | @master/icons |
npm install @master/icons-reactWith other package managers, use bun add, pnpm add or yarn add with the same name. Install only the package for your framework; the others are not needed. The packages support Node.js 22 and later, and the Astro package requires Node.js 24 or later.
#Render an icon
Import each icon by name. Icon components end in Icon.
import { SearchIcon } from '@master/icons-react';<SearchIcon size={20} label="Search" />Icons draw in currentColor, so they take the color of the surrounding text. Without options, an icon renders the 24 px drawing with soft corners. Browse every name, copy its import and download SVG files in the collection.
#Choose an entry
Each package has two kinds of entry, with the same icon names:
- Dynamic, such as
@master/icons-react: each icon carries all nine drawings (three optical sizes by three corner styles) and acceptssize,cornerandstrokeWidth. - Fixed, such as
@master/icons-react/20/soft: each icon carries one drawing. Use it when the whole interface uses one size and corner style; it ships less.
import { SearchIcon } from '@master/icons-react/20/soft';<button aria-label="Search"><SearchIcon /></button>Unused icons are removed by any bundler that supports tree shaking. Continue with the page for your framework: SVG and JavaScript, React, Vue, Svelte, Preact or Astro.
#Set up with an AI agent
A coding agent can run this setup for you. Paste the prompt below into the agent from the app's root directory. It inspects the project and asks for the framework package, the default size, corners and stroke, and what happens to an existing icon library before changing files. Then it installs the package, renders a first icon and runs your checks.
You are working in an existing web application. Set up Master Icons end to end. Documentation: https://icons.master.co/llms.txt, which links every guide as Markdown (read getting-started, the page for the chosen framework, optical-sizes, stroke-width and accessibility), and the README of the installed package. After installing, follow node_modules/@master/icons/skills/master-icons/SKILL.md. Master Icons is published on npm as @master/icons (the core) and one package per framework: @master/icons-react, @master/icons-vue, @master/icons-svelte, @master/icons-preact and @master/icons-astro. Install only these names; do not install a package with a similar name. First inspect the project before editing: package manager and lockfile, Node.js version, framework and build tool (React, Vue, Svelte, Preact, Astro or none), any icon library already in use and how it is imported, the dev/lint/build/test commands, and agent guidance files such as AGENTS.md. Before editing, ask me these and wait for the answers. Do not choose them yourself: - Integration: the package for the framework you found, or @master/icons for plain SVG and JavaScript. Install exactly one package. - Defaults: the optical size (16, 20 or 24; 24 for a general interface, 16 or 20 for a dense one), the corner style (sharp, soft or rounded; soft is the default), and whether to keep each master's native stroke or set one width (0.75–1.5 at 16 px, 1–2 at 20 px, 1.25–2.5 at 24 px, in steps of 0.25). - Existing icons: if the project already uses another icon library, whether to leave it in place (the default) and use Master Icons only for new screens, or replace the icons I name. Never replace icons I have not named. Then adopt Master Icons conservatively: 1. Run every command from the app root, where its package.json lives, with the project's package manager, and install the chosen package from npm. 2. Import each icon by name. The dynamic entry (import { SearchIcon } from '@master/icons-react') accepts size, corner and strokeWidth; a fixed entry such as '@master/icons-react/20/soft' holds one master and ships less. Prefer fixed entries when the app uses one setting everywhere. 3. Render icons at their native sizes. Pass size, which chooses the nearest optical master, instead of resizing an icon with CSS width and height. strokeWidth chooses precomputed geometry, so never override stroke-width in CSS. 4. Keep icons accessible: an icon beside visible text stays decorative, an icon-only button carries its accessible name on the button, and a meaningful standalone icon gets label. 5. If I chose to replace named icons, map each one to the closest name in node_modules/@master/icons/dist/catalog.json, show me the mapping before editing, keep every control's accessible name, and remove the old dependency only after nothing imports it. 6. Preserve the existing architecture and styling, and avoid unrelated refactors. 7. Verify: render a SearchIcon at size 20 on a visible page and confirm it draws in the text color with soft corners in light and dark mode. Then remove it unless I want to keep it, and run the project's lint, build and tests. When finished, summarize the changed files, the package installed, the defaults chosen, the icons replaced or intentionally left unchanged, the validation results, and anything not verified in a browser.
#For AI agents
Two resources keep a coding agent on real names and the rules above:
- Agent skill.
@master/iconsships a skill atnode_modules/@master/icons/skills/master-icons/SKILL.md. Copy themaster-iconsfolder into your agent's skills folder, such as.claude/skillsor.agents/skills. It covers packages, entries, sizes, stroke width and accessibility, and includes a script that searches the installed catalog so the agent never invents an icon name:node node_modules/@master/icons/skills/master-icons/scripts/search.mjs search. - llms.txt. /llms.txt indexes every guide as Markdown, and /llms-full.txt holds them in one file. Every guide page is also available as Markdown by adding
.mdto its address, such as /guide/getting-started.md.
#Next steps
- Choose a drawing for the space available in sizes and corners.
- Adjust line weight with stroke width.
- Name icons and the controls around them in accessibility.
- See how Master Icons differs from other libraries in the comparison.