Setup

Get started with RetroUI in just a few simple steps.

Initialize

Start by creating a new project. The setup requires a NextJS/ ReactJS app with Typescript & Tailwind.

For NextJS:

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

For ReactJS:

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

To add tailwind, you can follow these docs.

Installation

Install RetroUI using npm:

npm i pixel-retroui@latest

RetroUI v2.0.0 gives you the option to use the default Minecraft font or your own fonts. You can select your preference during setup.

Configuration

Choose one of the following setup methods:

CLI Setup (Recommended)

Run the CLI setup tool to configure RetroUI for your project:

npx pixel-retroui

The CLI will guide you through selecting font options and create the necessary setup files for your project.

After setup, import the generated file in your Next.js layout file:

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

Or

Manual Setup

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

You might need to add "use client"; on top of your page when using React Server Components in Next.js.
For the most reliable font loading, use our CLI setup: npx pixel-retroui

If you're using manual setup, make sure you've imported both CSS files.

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.0.0 or higher, which includes improved TypeScript compatibility.

Next Steps

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