Get Started

Install Mako UI and render your first component.

Requirements

React 19 or later
Tailwind CSS v4 — Mako's theme and components are built on v4 syntax
Next.js 16 — optional, and only for the mako-ui/fonts entry point. Everything else is framework-agnostic.

Installation

Mako UI lives on the public npm registry, so there is no registry configuration, .npmrc entry, or auth token to set up. Install it:


pnpm add mako-ui

That pulls v5.1.0, the version these docs are written against. See the Changelog for what each release changed.

Then import the theme once in your global stylesheet, after Tailwind:

app/globals.css

@import "tailwindcss";
@import "mako-ui/globals.css";

That brings in the color tokens, the type scale, and the sidebar variables. It also declares its own @source, so there is no content configuration to add on your side.

Now import components where you need them:

import { Button } from "mako-ui/components/button";
 
export function Example() {
  return <Button>Click me</Button>;
}

Fonts

Mako components read three CSS custom properties for typography:

Variable	Used by
`--font-sans`	Body text, buttons, labels, most UI
`--font-mono`	Code blocks, `<kbd>`, monospace text
`--font-heading`	Dialog, AlertDialog, Sheet, Drawer and Empty titles

The package ships the Mako variable font for all three. In a Next.js app, import it from mako-ui/fonts and apply the variable classes on <body>:

app/layout.tsx

import { fontSans, fontHeading, fontMono } from "mako-ui/fonts";
 
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body
        className={`${fontSans.variable} ${fontHeading.variable} ${fontMono.variable} font-sans`}
      >
        {children}
      </body>
    </html>
  );
}

Outside Next.js, import the stylesheet instead — it declares the same three variables with plain @font-face rules:

app/globals.css

@import "tailwindcss";
@import "mako-ui/globals.css";
@import "mako-ui/fonts.css";

Using a different typeface is fine, as long as it is exposed under those three variable names. See Typography for the details.

Portal isolation

Dialogs, popovers, selects and other portaled components need a stacking context to render above page content. Wrap your app in an isolated root:

app/layout.tsx

<body className="relative">
  <div className="isolate relative flex min-h-svh flex-col">{children}</div>
</body>

Styling explains why, including the position: relative on <body> that iOS Safari needs.

Entry points

Import	Contents
`mako-ui/components/<name>`	Components, one module per component
`mako-ui/globals.css`	Theme: tokens, type scale, radii
`mako-ui/fonts`	`fontSans`, `fontHeading`, `fontMono` (Next.js)
`mako-ui/fonts.css`	`@font-face` equivalent for other frameworks
`mako-ui/icons/<name>`	The Rubix icon set, one module per icon
`mako-ui/lib/utils`	`cn()`

There is no package-level barrel export: import from the component's — or the icon's — own module, so bundlers only pull in what you use.

import { Button } from "mako-ui/components/button";
import { Plus } from "mako-ui/icons/plus";
import { cn } from "mako-ui/lib/utils";

Customizing a component

Components come styled with the Rubix design system, and that's the intended way to use them. When you need to adapt one, do it from the outside:

className — merged with the component's own classes, so you can adjust spacing, width or colors without touching internals.
Design tokens — redefine a semantic token and every component follows. See Styling.
data-slot selectors — every element a component renders carries one, so you can reach an internal part from a parent: [&_[data-slot=input]]:text-right.
variant and size props — the supported variations are already there; check the component's page before styling around them.

Working with coding agents

The documentation is structured so coding agents can read it directly:

Bundled docs — the API of all 55 components ships inside the package at node_modules/mako-ui/dist/docs/, matched to the version you installed. Point your agent at that path from an AGENTS.md at your project root and it stops guessing Mako's API. Set it up.
llms.txt — a map of the documentation for agents that consume one.
Raw Markdown — every page has a Copy Markdown button, and appending .md to any docs URL returns its source.

On This Page

Requirements Installation Fonts Portal isolation Entry points Customizing a component Working with coding agents