mirror of
https://github.com/nextui-org/nextui.git
synced 2025-12-08 19:26:11 +00:00
335 lines
8.6 KiB
Plaintext
335 lines
8.6 KiB
Plaintext
---
|
||
title: Installation
|
||
description: Get started with HeroUI in the official documentation, and learn more about all our features!
|
||
---
|
||
|
||
# Installation
|
||
|
||
Requirements:
|
||
|
||
- [React 18](https://reactjs.org/) or later
|
||
- [Tailwind CSS 3.4](https://tailwindcss.com/) or later
|
||
- [Framer Motion 11.9](https://www.framer.com/motion/) or later
|
||
|
||
---
|
||
|
||
<CarbonAd/>
|
||
|
||
## Automatic Installation
|
||
|
||
Using the CLI is now the easiest way to start a HeroUI project. You can initialize your project and add components directly via the CLI:
|
||
|
||
<Steps>
|
||
|
||
### Installation
|
||
Execute one of the following commands in your terminal:
|
||
<PackageManagers
|
||
commands={{
|
||
npm: "npm install -g heroui-cli",
|
||
yarn: "yarn global add heroui-cli",
|
||
pnpm: "pnpm add -g heroui-cli",
|
||
bun: "bun add -g heroui-cli",
|
||
}}
|
||
/>
|
||
|
||
### Initialization and Starting the App
|
||
Initialize the project by using the `init` command.
|
||
```bash
|
||
heroui init my-heroui-app
|
||
```
|
||
|
||
You will be prompted to configure your project:
|
||
|
||
```bash
|
||
◇ Select a template (Enter to select)
|
||
│ ● App (A Next.js 14 with app directory template pre-configured with HeroUI (v2) and Tailwind CSS.)
|
||
│ ○ Pages (A Next.js 14 with pages directory template pre-configured with HeroUI (v2) and Tailwind CSS.)
|
||
│ ○ Vite (A Vite template pre-configured with HeroUI (v2) and Tailwind CSS.)
|
||
```
|
||
|
||
Install the dependencies to start the local server:
|
||
<PackageManagers
|
||
commands={{
|
||
npm: "cd my-heroui-app && npm install",
|
||
yarn: "cd my-heroui-app && yarn install",
|
||
pnpm: "cd my-heroui-app && pnpm install",
|
||
bun: "cd my-heroui-app && bun install",
|
||
}}
|
||
/>
|
||
|
||
Start the local server:
|
||
<PackageManagers
|
||
commands={{
|
||
npm: "npm run dev",
|
||
yarn: "yarn run dev",
|
||
pnpm: "pnpm run dev",
|
||
bun: "bun run dev",
|
||
}}
|
||
/>
|
||
|
||
### Adding the Components
|
||
Once your HeroUI project is ready to develop, you can add individual components using the CLI. For example, to add a button component:
|
||
|
||
```bash
|
||
heroui add button
|
||
```
|
||
|
||
This command adds the Button component to your project and manages all related dependencies.
|
||
|
||
You can also add multiple components at once:
|
||
|
||
```bash
|
||
heroui add button input
|
||
```
|
||
|
||
Or you can add the main library `@heroui/react` by running the following command:
|
||
|
||
```bash
|
||
heroui add --all
|
||
```
|
||
|
||
If you leave out the component name, the CLI will prompt you to select the components you want to add.
|
||
|
||
```bash
|
||
? Which components would you like to add? › - Space to select. Return to submit
|
||
Instructions:
|
||
↑/↓: Highlight option
|
||
←/→/[space]: Toggle selection
|
||
[a,b,c]/delete: Filter choices
|
||
enter/return: Complete answer
|
||
|
||
Filtered results for: Enter something to filter
|
||
|
||
◯ accordion
|
||
◯ autocomplete
|
||
◯ avatar
|
||
◯ badge
|
||
◯ breadcrumbs
|
||
◉ button
|
||
◯ card
|
||
◯ checkbox
|
||
◯ chip
|
||
◯ code
|
||
```
|
||
|
||
</Steps>
|
||
|
||
## Manual Installation
|
||
|
||
If you prefer not to use the CLI, you may try either global installation or individual installation to set up HeroUI in your project:
|
||
|
||
### Global Installation
|
||
|
||
The easiest way to get started with HeroUI is to use the global installation, which means
|
||
that all the components are imported from a single package.
|
||
|
||
Follow the steps below to install all HeroUI components:
|
||
|
||
<Steps>
|
||
|
||
#### Install Packages
|
||
|
||
To install HeroUI, run one of the following commands in your terminal:
|
||
|
||
<PackageManagers
|
||
commands={{
|
||
npm: "npm install @heroui/react framer-motion",
|
||
yarn: "yarn add @heroui/react framer-motion",
|
||
pnpm: "pnpm add @heroui/react framer-motion",
|
||
bun: "bun add @heroui/react framer-motion"
|
||
}}
|
||
/>
|
||
|
||
#### Hoisted Dependencies Setup
|
||
|
||
<Blockquote color="primary">
|
||
**Note**: This step is only for those who use `pnpm` to install. If you install HeroUI using other package managers, you may skip this step.
|
||
</Blockquote>
|
||
|
||
If you are using pnpm, you need to add the following line to your `.npmrc` file to hoist our packages to the root `node_modules`.
|
||
|
||
```bash
|
||
public-hoist-pattern[]=*@heroui/*
|
||
```
|
||
|
||
After modifying the `.npmrc` file, you need to run `pnpm install` again to ensure that the dependencies are installed correctly.
|
||
|
||
#### Tailwind CSS Setup
|
||
|
||
HeroUI is built on top of Tailwind CSS, so you need to install Tailwind CSS first. You can follow the official
|
||
[installation guide](https://tailwindcss.com/docs/installation) to install Tailwind CSS. Then you need to add
|
||
the following code to your `tailwind.config.js` file:
|
||
|
||
<Blockquote color="primary">
|
||
**Note**: If you are using pnpm and monorepo architecture, please make sure you are pointing to the ROOT `node_modules`
|
||
</Blockquote>
|
||
|
||
```js
|
||
// tailwind.config.js
|
||
const {heroui} = require("@heroui/react");
|
||
|
||
/** @type {import('tailwindcss').Config} */
|
||
module.exports = {
|
||
content: [
|
||
// ...
|
||
// make sure it's pointing to the ROOT node_module
|
||
"./node_modules/@heroui/theme/dist/**/*.{js,ts,jsx,tsx}",
|
||
],
|
||
theme: {
|
||
extend: {},
|
||
},
|
||
darkMode: "class",
|
||
plugins: [heroui()],
|
||
};
|
||
```
|
||
|
||
#### Provider Setup
|
||
|
||
It is essential to add the `HeroUIProvider` at the `root` of your application.
|
||
|
||
```jsx
|
||
import * as React from "react";
|
||
|
||
// 1. import `HeroUIProvider` component
|
||
import {HeroUIProvider} from "@heroui/react";
|
||
|
||
function App() {
|
||
// 2. Wrap HeroUIProvider at the root of your app
|
||
return (
|
||
<HeroUIProvider>
|
||
<YourApplication />
|
||
</HeroUIProvider>
|
||
);
|
||
}
|
||
```
|
||
|
||
</Steps>
|
||
|
||
### Individual Installation
|
||
|
||
HeroUI is also available as individual packages. You can install each package separately. This
|
||
is useful if you want to reduce the size of your CSS bundle as it will only include styles for the components
|
||
you're actually using.
|
||
|
||
<Blockquote color="primary">
|
||
**Note**: JavaScript bundle size will not change due to tree shaking support in HeroUI.
|
||
</Blockquote>
|
||
|
||
Follow the steps below to install each package separately:
|
||
|
||
<Steps>
|
||
|
||
#### Install Core Packages
|
||
|
||
Although you can install each package separately, you need to install the core packages first
|
||
to ensure that all components work correctly.
|
||
|
||
Run one of the following commands in your terminal to install the core packages:
|
||
|
||
<PackageManagers
|
||
commands={{
|
||
npm: "npm install @heroui/theme @heroui/system framer-motion",
|
||
yarn: "yarn add @heroui/theme @heroui/system framer-motion",
|
||
pnpm: "pnpm add @heroui/theme @heroui/system framer-motion",
|
||
bun: "bun add @heroui/theme @heroui/system framer-motion"
|
||
}}
|
||
/>
|
||
|
||
#### Install Component
|
||
|
||
Now, let's install the component you want to use. For example, if you want to use the
|
||
[Button](/docs/components/button) component, you need to run one of the following commands
|
||
in your terminal:
|
||
|
||
<PackageManagers
|
||
commands={{
|
||
npm: "npm install @heroui/button",
|
||
yarn: "yarn add @heroui/button",
|
||
pnpm: "pnpm add @heroui/button",
|
||
bun: "bun add @heroui/button"
|
||
}}
|
||
/>
|
||
|
||
#### Hoisted Dependencies Setup
|
||
|
||
<Blockquote color="primary">
|
||
**Note**: This step is only for those who use `pnpm` to install. If you install HeroUI using other package managers, you may skip this step.
|
||
</Blockquote>
|
||
|
||
If you are using pnpm, you need to add the following line to your `.npmrc` file to hoist our packages to the root `node_modules`.
|
||
|
||
```bash
|
||
public-hoist-pattern[]=*@heroui/*
|
||
```
|
||
|
||
After modifying the `.npmrc` file, you need to run `pnpm install` again to ensure that the dependencies are installed correctly.
|
||
|
||
#### Tailwind CSS Setup
|
||
|
||
TailwindCSS setup changes a bit when you use individual packages. You only need to add the
|
||
styles of the components you're using to your `tailwind.config.js` file. For example, for the
|
||
[Button](/docs/components/button) component, you need to add the following code to your
|
||
`tailwind.config.js` file:
|
||
|
||
```js
|
||
// tailwind.config.js
|
||
const {heroui} = require("@heroui/theme");
|
||
|
||
/** @type {import('tailwindcss').Config} */
|
||
module.exports = {
|
||
content: [
|
||
// single component styles
|
||
"./node_modules/@heroui/theme/dist/components/button.js",
|
||
// or you can use a glob pattern (multiple component styles)
|
||
'./node_modules/@heroui/theme/dist/components/(button|snippet|code|input).js'
|
||
],
|
||
theme: {
|
||
extend: {},
|
||
},
|
||
darkMode: "class",
|
||
plugins: [heroui()],
|
||
};
|
||
```
|
||
|
||
#### Provider Setup
|
||
|
||
It is essential to add the `HeroUIProvider` at the `root` of your application.
|
||
|
||
```jsx
|
||
import * as React from "react";
|
||
|
||
// 1. import `HeroUIProvider` component
|
||
import {HeroUIProvider} from "@heroui/system";
|
||
|
||
function App() {
|
||
// 2. Wrap HeroUIProvider at the root of your app
|
||
return (
|
||
<HeroUIProvider>
|
||
<YourApplication />
|
||
</HeroUIProvider>
|
||
);
|
||
}
|
||
```
|
||
|
||
#### Use the Component
|
||
|
||
Now, you can use the component you installed in your application:
|
||
|
||
```jsx
|
||
import * as React from "react";
|
||
import {Button} from "@heroui/button";
|
||
|
||
function App() {
|
||
return (
|
||
<Button>Press me</Button>
|
||
);
|
||
}
|
||
```
|
||
</Steps>
|
||
|
||
## Framework Guides
|
||
|
||
HeroUI is compatible with your preferred framework. We have compiled comprehensive, step-by-step tutorials for the following frameworks:
|
||
|
||
<Frameworks />
|