export const title = "Install Untitled UI Icons"
export const description = "Untitled UI Icons are a clean, consistent, and neutral icon library crafted for modern UI design. These icons are available as React components with instant npm access."
export const metaDescription = "Learn how to install, import, and style Untitled UI Icons. Untitled UI Icons are a clean, consistent, and neutral icon library crafted for modern UI design."
export const titleParts = "Untitled UI — Icons"

<Divider />

## Installation

To get started, install the Untitled UI Icons package:

<CodeTabs>
    <CodeTabList items={[
        { id: "npm", label: "npm" },
        { id: "yarn", label: "yarn" },
        { id: "bun", label: "bun" }
    ]}/>
    <CodeTabPanel id="npm">
        ```bash
        npm install @untitledui/icons
        ```
    </CodeTabPanel>
    <CodeTabPanel id="yarn">
        ```bash
        yarn add @untitledui/icons
        ```
    </CodeTabPanel>
    <CodeTabPanel id="bun">
        ```bash
        bun add @untitledui/icons
        ```
    </CodeTabPanel>
</CodeTabs>

<Divider />

## Using Untitled UI Icons

You can use Untitled UI Icons in two ways: by importing from the default import or by importing individual icon files. Here's a quick guide for both:

### Main module import (recommended)

For modern build tools that support tree-shaking (e.g. Next.js, Vite), you can import icons directly from the main package:

```tsx
import { 
  Home01, 
  Settings01, 
  User01, 
  Bell01 
} from "@untitledui/icons";

<Home01 className="size-5" />
<Settings01 className="size-5" />
<User01 className="size-5" />
<Bell01 className="size-5" />
```

This method ensures that only the icons you use are included in the final bundle, keeping your bundle size small and optimized.

### Individual module import

If you're using a build tool that doesn't fully support tree-shaking, you can import icons directly from individual files just as easily:

```tsx
import Home01 from "@untitledui/icons/Home01";
import Settings01 from "@untitledui/icons/Settings01";
import User01 from "@untitledui/icons/User01";
import Bell01 from "@untitledui/icons/Bell01";

<Home01 className="size-5" />
<Settings01 className="size-5" />
<User01 className="size-5" />
<Bell01 className="size-5" />
```

This ensures that only the icons you explicitly import are included in your bundle.

<Divider />

## Styling Untitled UI Icons

All Untitled UI Icons support standard SVG and React props out of the box:

```tsx
import { Home01 } from "@untitledui/icons";

<Home01 
  className="size-6 text-brand-600" 
  aria-hidden="true"
  strokeWidth={1.5}
  onClick={() => console.log("Home icon clicked")}
/>
```

You can customize icons using the following common SVG and React props:

- `className` – Apply utility classes to control size, color, spacing, and more.
- `strokeWidth` – Adjust the thickness of the icon's strokes.
- `color` – Set the icon color (using `className` for text color is recommended).
- `aria-hidden` – Set to `true` for decorative icons to improve accessibility.

<Divider />

## Untitled UI Icons PRO

The PRO version of [Untitled UI Icons](https://www.untitledui.com/icons) includes 4,600+ icons across 4 styles. Choose between minimal line, modern duocolor or duotone, or solid icon styles.

If you've purchased the PRO version of Untitled UI Icons, you'll need to configure your package manager with your private access token:

<Steps>
    <Step title="Create a configuration file">
      Start by creating a configuration file in your project root:

      <CodeTabs>
          <CodeTabList items={[
              { id: "npm", label: "npm" },
              { id: "yarn", label: "yarn" },
              { id: "bun", label: "bun" }
          ]}/>
          <CodeTabPanel id="npm">
              ```bash
              # .npmrc

              @untitledui-pro:registry=https://pkg.untitledui.com
              //pkg.untitledui.com/:_authToken=YOUR_TOKEN_HERE
              ```
          </CodeTabPanel>
          <CodeTabPanel id="yarn">
              ```yaml
              # .yarnrc.yml

              npmScopes:
                untitledui-pro:
                  npmRegistryServer: "https://pkg.untitledui.com"
                  npmAuthToken: "YOUR_TOKEN_HERE"
              ```
          </CodeTabPanel>
          <CodeTabPanel id="bun">
              ```yaml
              # bunfig.toml

              [install.scopes]
              "untitledui-pro" = { url = "https://pkg.untitledui.com", token = "YOUR_TOKEN_HERE" }
              ```
          </CodeTabPanel>
      </CodeTabs>
    </Step>
    <HideBasedOnPermission permission="has_icons">
        <Step title="Add your private access token">
            Replace `YOUR_TOKEN_HERE` with your private access token:

            <div className="not-typography mt-5">
                <FileCard
                    type="npm"
                    access="icons"
                    title="Untitled UI Icons – PRO npm"
                    subtitle="Configure your package manager with your private access token:"
                    noAccessSubtitle="Upgrade to Untitled UI Icons PRO to unlock 4,600+ icons across 4 styles."
                />
            </div>
        </Step>
    </HideBasedOnPermission>
    <Step title="Installing icons">
      Once you've set up access, you can install the PRO icons with a single command:

      <CodeTabs>
        <CodeTabList items={[
            { id: "npm", label: "npm" },
            { id: "yarn", label: "yarn" },
            { id: "bun", label: "bun" }
        ]}/>
        <CodeTabPanel id="npm">
            ```bash
            npm install @untitledui-pro/icons
            ```
        </CodeTabPanel>
        <CodeTabPanel id="yarn">
            ```bash
            yarn add @untitledui-pro/icons
            ```
        </CodeTabPanel>
        <CodeTabPanel id="bun">
            ```bash
            bun add @untitledui-pro/icons
            ```
        </CodeTabPanel>
    </CodeTabs>
    </Step>
    <Step title="Importing different styles">
        The PRO version of Untitled UI Icons includes multiple style variants—line, duocolor, duotone, and solid—each available via separate imports:

        ```tsx
          // Line icons (also available in the free package)
          import { Home01, Settings01 } from "@untitledui-pro/icons/line";

          // Solid icons
          import { Home01, Settings01 } from "@untitledui-pro/icons/solid";

          // Duocolor icons
          import { Home01, Settings01 } from "@untitledui-pro/icons/duocolor";

          // Duotone icons
          import { Home01, Settings01 } from "@untitledui-pro/icons/duotone";

          <Home01 className="size-6" />
        ```
    </Step>
</Steps>

### Installing in CI/CD

In CI/CD pipelines or other automated environments, you can't complete a browser-based login—and you should never commit your private access token to source control. Instead, store your token as a secret and read it from an environment variable at build time.

<Steps>
    <Step title="Add your token as a secret">
        In your CI provider (GitHub Actions, GitLab CI, Vercel, etc.), add your private access token as a secret or environment variable—for example, `UNTITLEDUI_PRO_TOKEN`.
    </Step>
    <Step title="Reference the token from your config file">
        Update your configuration file to read the token from the environment instead of hardcoding it. This file is safe to commit, since it no longer contains the token itself:

        <CodeTabs>
            <CodeTabList items={[
                { id: "npm", label: "npm" },
                { id: "yarn", label: "yarn" },
                { id: "bun", label: "bun" }
            ]}/>
            <CodeTabPanel id="npm">
                ```bash
                # .npmrc

                @untitledui-pro:registry=https://pkg.untitledui.com
                //pkg.untitledui.com/:_authToken=${UNTITLEDUI_PRO_TOKEN}
                ```
            </CodeTabPanel>
            <CodeTabPanel id="yarn">
                ```yaml
                # .yarnrc.yml

                npmScopes:
                  untitledui-pro:
                    npmRegistryServer: "https://pkg.untitledui.com"
                    npmAuthToken: "${UNTITLEDUI_PRO_TOKEN}"
                ```
            </CodeTabPanel>
            <CodeTabPanel id="bun">
                ```yaml
                # bunfig.toml

                [install.scopes]
                "untitledui-pro" = { url = "https://pkg.untitledui.com", token = "$UNTITLEDUI_PRO_TOKEN" }
                ```
            </CodeTabPanel>
        </CodeTabs>
    </Step>
    <Step title="Install during your build">
        With the token available in the environment, your package manager will authenticate automatically and install the PRO icons:

        <CodeTabs>
            <CodeTabList items={[
                { id: "npm", label: "npm" },
                { id: "yarn", label: "yarn" },
                { id: "bun", label: "bun" }
            ]}/>
            <CodeTabPanel id="npm">
                ```bash
                npm install @untitledui-pro/icons
                ```
            </CodeTabPanel>
            <CodeTabPanel id="yarn">
                ```bash
                yarn add @untitledui-pro/icons
                ```
            </CodeTabPanel>
            <CodeTabPanel id="bun">
                ```bash
                bun add @untitledui-pro/icons
                ```
            </CodeTabPanel>
        </CodeTabs>
    </Step>
</Steps>

<Divider />

<FAQ
    faqs={[
        {
            question: "What are Untitled UI Icons?",
            answer: "[Untitled UI Icons](https://www.untitledui.com/icons) are a clean, consistent, and neutral icon library crafted specifically for modern UI design. Made for Figma, in Figma, and now [available for React](https://www.untitledui.com/react/docs/icons)!",
        },
        {
            question: "Are Untitled UI Icons free?",
            answer: "Yes, the free version of Untitled UI Icons includes the default **line** style—1,100+ icons that you can use in unlimited personal and commercial projects, without attribution.\n\nThe PRO version of [Untitled UI Icons](https://www.untitledui.com/icons) includes 4,600+ icons across 4 styles, as well as access to the private npm package. Choose between minimal **line**, modern **duocolor** or **duotone**, or **solid** icon styles.",
        },
        {
            question: "Are Untitled UI Icons available in additional styles?",
            answer: "The PRO version of Untitled UI Icons includes 4,600+ icons across 4 styles: **line**, **duocolor**, **duotone**, and **solid**.",
        },
        {
            question: "Can I customize the color and size of the icons?",
            answer: "Customizing icons is simple and works just like standard CSS. Use text utility classes (e.g. `text-brand-600`) to change color, size classes (e.g. `size-6`) to adjust dimensions, and the `strokeWidth` prop to control line thickness.",
        },
        {
            question: "Do I need to import icons individually to optimize bundle size?",
            answer: "You don't need to import icons individually if you're using a modern bundler like Next.js or Vite. These support tree-shaking and will automatically include only the icons you use. For older build tools, individual imports may be recommended to optimize bundle size.",
        },
        {
            question: "How do I get access to Untitled UI Icons PRO?",
            answer: "The PRO version of [Untitled UI Icons](https://www.untitledui.com/icons) includes 4,600+ icons across 4 styles, as well as access to the private npm package.\n\nIf you've purchased Untitled UI Icons PRO, you can unlock additional styles by configuring your package manager with your private access token. Follow our step-by-step guide [here](https://www.untitledui.com/react/docs/icons#untitled-ui-icons-pro).",
        },
    ]}
/>