Setup

Get started with RetroUI in just a few simple steps.

Initialize

Start by creating a new project. The setup requires a Next.js/ React app with Typescript & Tailwind.

For Next.js:

npx create-next-app@latest my-app --typescript --tailwindcss

For React:

npx create-react-app my-app --template typescript

To add tailwind, you can follow these docs.

Setup

Choose one of the following setup methods:

CLI Setup (Recommended)

1. Run the CLI setup tool

npx pixel-retroui

2. The CLI will automatically install the package and configure files based on your preferences.

CLI output preview:
      ▄▀▄─────▄▀▄
     ▄█░░▀▀▀▀▀░░█▄
─▄▄──█░░░░░░░░░░░█──▄▄
█▄▄█─█░░▀░░┬░░▀░░█─█▄▄█
Setting up pixel-retroui...
Installing pixel-retroui...
Would you like to use the default Minecraft font?
Which framework are you using?
.
.
.
🎉 Setup complete! Enjoy using pixel-retroui!

3. For Next.js, in your layout.tsx file:

import '@/lib/pixel-retroui-setup.js';

Setup Complete!

You're now ready to use RetroUI components in your project.

Or

Manual Setup

1. Install RetroUI:

npm i pixel-retroui@latest

2. Add the following import to your main CSS file:
globals.css in Next.js or index.css in React

@import 'pixel-retroui/dist/index.css';

In manual setup,

If you want to use the default Minecraft font, add this to your CSS too:

 @import 'pixel-retroui/dist/fonts.css';

Basic Usage

Now you can use the components in your React application:

import React from 'react';
import { Button, Card } from 'pixel-retroui';


function App() {
  return (
    <div>
      <h1 className="text-2xl font-minecraft mb-4">Welcome to My Retro App</h1>
      <Card className="p-4 mb-4">
        <h2>This is a pixel-styled card</h2>
        <p>You can put anything inside!</p>
      </Card>
      <Button>Click me!</Button>
    </div>
  );
}


export default App;

Customization

RetroUI components can be customized using props and TailwindCSS classes. Here's an example of customizing a button:

<Button 
  bg="#c381b5" 
  textColor="#fefcd0"
  shadow="#fefcd0"
  className="px-6 py-2"
>
  Custom Button
</Button>

Troubleshooting

For the most reliable font loading, use our CLI setup: npx pixel-retroui

In manual, make sure you're using the correct path in your imports:@import 'pixel-retroui/dist/fonts.css';Common mistake:@import 'pixel-retroui/dist.fonts.css';

Use font-minecraft to add Minecraft font to your text.

Make sure you've imported the library's CSS file in your main CSS file:

@import 'pixel-retroui/dist/index.css';If you're using the Minecraft font:
@import 'pixel-retroui/dist/fonts.css';
Ensure that you have added important: true in tailwind.config.ts to ensure our styles don't get overridden.
If you're seeing TypeScript errors with Next.js 19+ or React 19+, make sure you're using pixel-retroui v2.1.0 or higher, which includes improved TypeScript compatibility.

Next Steps

Explore

Contribute

Need more help? Feel free to open an issue on GitHub or drop a dm on Twitter.

Support the project ☕

If you find this library useful, consider supporting its development!