Make anything buttery

The four ways to bring buttery into an app, from wiring up the provider to whole-page patterns.

There are four levels of effort for making an app buttery, numbered 0 to 3, and each adds to the one before. Start at the first and stop wherever the app feels right: nothing at a higher level is required.

The four levels

0. Wire it up

   Import the stylesheets once at the entry and wrap the app in ButteryProvider:

   src/main.tsx

   import "@butteryui/core/styles.css";
   import "@butteryui/react/styles.css";
   import type { ReactElement } from "react";
   import { ButteryProvider } from "@butteryui/react";
   import { App } from "./App.tsx";
   
   export function Root(): ReactElement {
     return (
       <ButteryProvider>
         <App />
       </ButteryProvider>
     );
   }

   That alone gives the whole app the tokens, Inter, focus rings, the selection color and scrollbars in light and dark, the layers and lanes that menus and toasts open into, motion presets that follow reduced motion, and LayoutGuard in development.

1. Wrap what you have

   The buttery factory turns any element or component into a buttery one, with token-typed props for its surface, padding, gap, press feedback and entrance:

   tsx

   import type { ReactElement } from "react";
   import { buttery } from "@butteryui/react";
   
   export function Receipt(): ReactElement {
     return (
       <buttery.div surface="card" pad={4} stack gap={3} enter="rise">
         Order 1042 is on its way.
       </buttery.div>
     );
   }

   buttery(Component, { surface: "raised", hover: "lift" }) does the same for a component from another library. Plain HTML can use the recipes as classes and attributes, such as class="bt-surface" data-level="card".

2. Compose components

   Build screens from buttery's components and primitives, as the quick start does: Stack, Inline and Grid for layout, and controls such as Button, Slider and SegmentedControl that already follow the layout and motion rules. All components lists every one by the job it does.

3. Start from a pattern

   Patterns are whole screens that already follow the rules, and templates are whole apps made from them:

   • An app

     AppShell with Sidebar, TopBar and AppPage, the App shell pattern, or the dashboard template.

   • A marketing page

     Page with a hero, a bento grid and a footer, the Marketing page pattern, or the marketing template.

Where to start

Make an existing app buttery walks through bringing a working app across, one screen at a time.