Medusa UI Installation in Standalone Projects

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

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 will need to install it in your project as well.
  • Medusa UI was built with Tailwind CSS v3, but it may generally support v4 as well.

Step 1: Install Medusa UI#

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

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:

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.

tailwind.config.js
1module.exports = {2  presets: [require("@medusajs/ui-preset")],3  content: [4    // ...5    "./node_modules/@medusajs/ui/dist/**/*.{js,jsx,ts,tsx}",6  ],7  // ...8}

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

tailwind.config.js
1const path = require("path")2
3const uiPath = path.resolve(4  require.resolve("@medusajs/ui"),5  "../..",6  "\*_/_.{js,jsx,ts,tsx}"7)8
9module.exports = {10  presets: [require("@medusajs/ui-preset")],11  content: [12    // ...13    uiPath,14  ],15  // ...16}

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 @config and @source directives:

Code
1@import "tailwindcss";2@source "../node_modules/@medusajs/ui";3@config "@medusajs/ui-preset";

This will explicitly include the Medusa UI preset and its components in your Tailwind CSS build, and will 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:

Code
1import { Button } from "@medusajs/ui"2
3export function ButtonDemo() {4  return <Button>Button</Button>5}

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 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:

package.json
1{2  "dependencies": {3    "@medusajs/ui": "4.0.0",4    "@medusajs/ui-preset": "4.0.0"5  }6}