Next.js

How to install SmartAC Ambient UI in a Next.js project.

To create a new Next.js project, run the following command:


bunx --bun create-next-app@latest my-next-app

Install the Ambient UI packages

Follow the instructions described in the General Installation guide to install the UI packages.


bun add @smartacteam/fonts @smartacteam/ambient-tokens @smartacteam/ambient-web

Install the peer dependencies

The package has peer dependencies that must be installed in your project. To install the peer dependencies, run the following command:


bun add date-fns react-hook-form zod

Ambient UI also requires Tailwind CSS to be set up in your Next.js project. To install Tailwind CSS, run the following command:


bun add -D tailwindcss @tailwindcss/postcss tw-animate-css

Configure Tailwind CSS

Add a global.css file in the src/app directory:

.
├── eslint.config.mjs
├── next-env.d.ts
├── next.config.ts
├── package.json
├── postcss.config.mjs
├── public/
├── README.md
├── src
│   ├── app
│   │   ├── page.tsx
│   │   ├── favicon.ico
│   │   ├── globals.css
│   │   └── layout.tsx
│   ├── components/
│   └── lib/
└── tsconfig.json

with the following content:

@import "tailwindcss";
@import "tw-animate-css";
 
@import "@smartacteam/ambient-tokens/tokens.css";
@import "@smartacteam/ambient-tokens/tokens-dark.css";
@import "@smartacteam/ambient-tokens/tokens-touch.css";
@import "@smartacteam/ambient-tokens/tailwind.css";
 
@source "../**/*.{ts,tsx}"; /* Current app */
@source "../../node_modules/@smartacteam/ambient-web/**/*.{ts,tsx}"; /* Any components in ui package*/
 
@layer base {
  * {
    @apply antialiased;
  }
 
  html {
    @apply scroll-smooth;
  }
 
  body {
    @apply border-stroke-default bg-surface-inset font-booton text-foreground-primary;
  }
}

Notice that we are pointing to the @smartacteam/ambient-web package as one of the sources. If you have a different folder structure, you may need to adjust the paths.

Import the CSS globals

If you created the Next.js project using the recommended options (App Router), you can import the CSS globals in the root layout.tsx file inside the app directory:

import "./globals.css";
 
import type { Metadata } from "next";
 
import { ABCOtto, Booton } from "@smartacteam/fonts";
 
export const metadata: Metadata = {
  title: "test",
  description: "Testing",
};
 
export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body className={`${ABCOtto.variable} ${Booton.variable} antialiased`}>
        {children}
      </body>
    </html>
  );
}

Adding a client-side root provider

Typically, you will want to add a root provider to your Next.js application to use context or other providers (Toaster, Themes, etc.). To do this, create a provider.tsx file in the app directory and add the following code:

"use client";
 
import { ThemeProvider } from "next-themes";
import * as React from "react";
 
import { Toaster } from "@smartacteam/ambient-web/toaster";
 
export function RootProvider({ children }: React.PropsWithChildren) {
  return (
    <ThemeProvider
      enableSystem
      attribute="class"
      defaultTheme="dark"
      enableColorScheme
      disableTransitionOnChange
      storageKey="smac-ui-theme"
    >
      <Toaster>{children}</Toaster>
    </ThemeProvider>
  );
}

And then use the RootProvider in the layout.tsx file:

import "./globals.css";
 
import type { Metadata } from "next";
 
import { ABCOtto, Booton } from "@smartacteam/fonts";
 
import { RootProvider } from "./provider";
 
export const metadata: Metadata = {
  title: "test",
  description: "Testing",
};
 
export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body className={`${ABCOtto.variable} ${Booton.variable} antialiased`}>
        <RootProvider>
          {children}
        </RootProvider>
      </body>
    </html>
  );
}

Using the components

You can now use the ambient components in your Next.js application. For example, to use the Button component inside a page.tsx file:

import { Button } from '@smartacteam/ambient-web/button';
 
export default function HomePage() {
  return (
    <div className="flex min-h-svh w-full items-center justify-center">
      <Button>Click me</Button>
    </div>
  );
}