import { Note } from "docs-ui"

export const metadata = { title: Install Medusa UI in Standalone Projects, }

{metadata.title}

In this guide, you'll learn how to install and use Medusa UI in a standalone project.

Medusa UI is a React UI library that, while intended for use within Medusa projects, can also be used in any React project.

The icons package is installed independently from Medusa UI. Learn how to install it in the Icons guide.

Medusa UI Compatibility

To use Medusa UI in your standalone project, you must have:

• React 18+ installed. Most React-based frameworks and libraries, such as Next.js and Vite, are compatible with this requirement.
• Tailwind CSS installed. The components in Medusa UI are styled using Tailwind CSS, so you'll need to install it in your project as well.
  • Medusa UI was built with Tailwind CSS v3, but it may also support v4.

Step 1: Install Medusa UI

In your standalone project, install the Medusa UI package with the following command:

npm install @medusajs/ui

Step 2: Install UI Presets

Medusa UI customizes Tailwind CSS classes to implement its design system, so you must also install the Medusa UI preset package.

To install the Medusa UI preset, run the following command:

npm install @medusajs/ui-preset --save-dev

Step 3: Configure Tailwind CSS

Next, you'll need to configure Tailwind CSS to use the Medusa UI preset and explicitly add the paths to the Medusa UI components as content files.

Tailwind CSS v3 Configurations

In Tailwind CSS v3, which is the recommended version to use with Medusa UI, you need to add the following configurations to your tailwind.config.js or tailwind.config.ts file:

1. Add the Medusa UI preset to the presets array.
2. Ensure that the content field includes the path to the Medusa UI package.

module.exports = {
  presets: [require("@medusajs/ui-preset")],
  content: [
    // ...
    "./node_modules/@medusajs/ui/dist/**/*.{js,jsx,ts,tsx}",
  ],
  // ...
}

If your project is in a monorepo, you'll need to resolve the path to the @medusajs/ui package from the monorepo root:

export const monorepoHighlights = [ ["3", "uiPath", "Resolve the UI package path from node_modules."], ["13"] ]

const path = require("path")

const uiPath = path.resolve(
  require.resolve("@medusajs/ui"),
  "../..",
  "\*_/_.{js,jsx,ts,tsx}"
)

module.exports = {
  presets: [require("@medusajs/ui-preset")],
  content: [
    // ...
    uiPath,
  ],
  // ...
}

Tailwind CSS v4 Configurations

Medusa UI isn't officially compatible with Tailwind CSS v4 yet, so use it with caution.

In your CSS file that imports Tailwind CSS, add the following @import, @config, and @source directives:

@import "tailwindcss";
@source "../node_modules/@medusajs/ui";
@config "@medusajs/ui-preset";

This will explicitly include the Medusa UI preset and its components in your Tailwind CSS build and apply the preset styles to your project.

Step 4: Use Medusa UI in Standalone Projects

You can now start building your application with Medusa UI.

For example, you can use the Button in your custom components:

import { Button } from "@medusajs/ui"

export function ButtonDemo() {
  return <Button>Button</Button>
}

Refer to the documentation of each component to learn about its props and usage.

Update UI Packages in Standalone Projects

Medusa's design system packages, including @medusajs/ui and @medusajs/ui-preset, are versioned independently from other @medusajs/* packages. However, they're still released as part of Medusa's releases.

So, to find the latest updates and breaking changes to any of these packages, refer to the release notes in the Medusa GitHub repository.

To update these packages in your standalone project, update their version in your package.json file and re-install dependencies. For example:

{
  "dependencies": {
    "@medusajs/ui": "4.0.0",
    "@medusajs/ui-preset": "4.0.0"
  }
}