Once UI Handbook
Beginner Guides
What is Once UI?
Install & config
Page skeleton
Your first page
Build And Launch
How to launch a portfolio site that actually gets you hired
How to build a documentation site with MDX and Next.js
How to ship a landing page and dashboard with authentication in Next.js
How to launch a social app with Next.js and Supabase
Vibe Coding
Introduction to vibe coding
Set up your local dev environment
Essential tools for vibe coding
Build your first Once UI app
Common Patterns
Hero section
Static panel
Form layout
Highlighted card
Responsive stacking
Decoration layers
Dialog & modal
Toast & feedback
Tables & lists
Loading states
App shell navigation
Dashboard & charts
Chat & messaging
Auth & verification
Settings & split panels
Data filters & toolbar
Command palette
Pricing & plans
Accordion & FAQ
Media & uploads
Empty & error states
SEO, Open Graph, and structured data
Documentation code blocks with live preview
Carousels, galleries, and before/after comparisons
Date pickers and scheduling
Context menus and dropdown actions
Tags, chips, and multi-value inputs
Roadmap & kanban
Form inputs & controls
Progress, status & badges
Scrolling & feeds
Profile, avatars & identity
Social proof & logo clouds
Masonry & media grids
Table pagination, search & bulk selection
Banners & announcements
Footer layouts
Onboarding & first run
Waitlist & coming soon
Design Tips
Color & surfaces
Harness overview
Row, Column & Grid
Spacing & rhythm
Icons & buttons
Reveal & motion
Theme tokens, FOUC-free init, and runtime style controls
Tooltips and hover cards
Block updates
Block updates changelog
Agent Resources
Column, not Flex
Semantics over CSS
Typography scale
Common gotchas
Block anchors
Validate generated code
Pro block registry
Match task bundles
TrademarkTrademark
Ctrl k
Search...
Sign up
Once UI Handbook
Beginner Guides
What is Once UI?
Install & config
Page skeleton
Your first page
Build And Launch
How to launch a portfolio site that actually gets you hired
How to build a documentation site with MDX and Next.js
How to ship a landing page and dashboard with authentication in Next.js
How to launch a social app with Next.js and Supabase
Vibe Coding
Introduction to vibe coding
Set up your local dev environment
Essential tools for vibe coding
Build your first Once UI app
Common Patterns
Hero section
Static panel
Form layout
Highlighted card
Responsive stacking
Decoration layers
Dialog & modal
Toast & feedback
Tables & lists
Loading states
App shell navigation
Dashboard & charts
Chat & messaging
Auth & verification
Settings & split panels
Data filters & toolbar
Command palette
Pricing & plans
Accordion & FAQ
Media & uploads
Empty & error states
SEO, Open Graph, and structured data
Documentation code blocks with live preview
Carousels, galleries, and before/after comparisons
Date pickers and scheduling
Context menus and dropdown actions
Tags, chips, and multi-value inputs
Roadmap & kanban
Form inputs & controls
Progress, status & badges
Scrolling & feeds
Profile, avatars & identity
Social proof & logo clouds
Masonry & media grids
Table pagination, search & bulk selection
Banners & announcements
Footer layouts
Onboarding & first run
Waitlist & coming soon
Design Tips
Color & surfaces
Harness overview
Row, Column & Grid
Spacing & rhythm
Icons & buttons
Reveal & motion
Theme tokens, FOUC-free init, and runtime style controls
Tooltips and hover cards
Block updates
Block updates changelog
Agent Resources
Column, not Flex
Semantics over CSS
Typography scale
Common gotchas
Block anchors
Validate generated code
Pro block registry
Match task bundles
TrademarkTrademark
Once UIDocumentationBlog
© Once UI. All rights reserved.
Built with Aveiro

Build your first Once UI app

Create your first Once UI app.
Updated 19d ago
Essential tools for vibe coding

Set up Once UI

We'll start with the Once UI Starter which gives us access to 100+ Once UI components and a minimalistic Next.js boilerplate. Clone the repository and set up the local environment as explained in the local environment setup guide.

Create the layout

Let's create two new components in the components folder: Header.tsx and Footer.tsx.
<Row fillWidth position="sticky" horizontal="center" paddingX="l" paddingTop="8" zIndex={1}>
    <Row maxWidth="l" paddingLeft="16" paddingRight="8" paddingY="8" background="surface" radius="l" border="neutral-medium" horizontal="between">
      <Row gap="40" vertical="center">
        <Logo href="/" size="s" dark wordmark="/trademarks/wordmark-dark.svg" />
        <Logo href="/" size="s" light wordmark="/trademarks/wordmark-light.svg" />
        <Row gap="20" textVariant="label-default-s" xs={{hide: true}}>
          <SmartLink href="/">Home</SmartLink>
          <SmartLink href="/about">About</SmartLink>
          <SmartLink href="/contact">Contact</SmartLink>
        </Row>
      </Row>
      <Row gap="8">
        <Button size="s" href="/signup" variant="secondary">Sign up</Button>
        <Button size="s" href="/login">Login</Button>
      </Row>
    </Row>
</Row>
The position="sticky" prop makes the header sticky, so it stays at the top of the page when scrolling. The light and dark props are used to conditionally render the logo based on the current theme. Don't forget to change the svg files to your own logo. The xs={{hide: true}} prop hides the navigation links on mobile.
<Row fillWidth horizontal="center" paddingX="l" background="surface" borderTop="neutral-medium">
    <Column maxWidth="l" padding="l" gap="32">
      <Logo href="/" dark icon="/trademarks/icon-dark.svg" size="s" />
      <Logo href="/" light icon="/trademarks/icon-light.svg" size="s" />
      <Row fillWidth horizontal="between" textVariant="label-default-s">
        <Column fillWidth gap="16">
          <Text variant="label-default-s" marginBottom="16">Product</Text>
          <SmartLink href="/">Home</SmartLink>
          <SmartLink href="/about">About</SmartLink>
          <SmartLink href="/contact">Contact</SmartLink>
        </Column>
        <Column fillWidth gap="16">
          <Text variant="label-default-s" marginBottom="16">Legal</Text>
          <SmartLink href="/privacy-policy">Privacy Policy</SmartLink>
          <SmartLink href="/terms-of-service">Terms of Service</SmartLink>
        </Column>
      </Row>
      <Text variant="label-default-s" paddingY="16" onBackground="neutral-weak">{new Date().getFullYear()} Once UI. All rights reserved.</Text>
    </Column>
</Row>
Now let's open the layout.tsx file and add the Header and Footer components to the layout. They will appear on every page.
Layout with header and footer

Update the page content

Now let's challenge the AI to update the page content. Open the page.tsx file and try this prompt:
"Update the @page.tsx file with a vertical hero section with a heading, subheading, call to action button and an image. Align the content to the center of the page. This is a SaaS product for designers. For the image, use "/images/og/home.jpg". Make sure you read the rules file to understand the constraints and the context7 documentation to understand the available components."
This is the result:
AI-generated hero section
It's a minimalistic, completely responsive hero element with fade-in animations. Now we can ask AI to create a features section, a testimonial, and pricing cards.
AI-generated landing page with features, testimonial, and pricing
This is not jaw-dropping, over-the-top or flashy. It's just a simple, responsive foundation that we can work with. You don't stand out from the crowd by being more flashy. You stand out by being more intentional.
Browse the Once UI documentation and copy-paste elements to spice it up a bit. I'll add a nice gradient behind the testimonial section to highlight it visually.
Customized testimonial section with gradient background
Even small changes like this one can have a huge impact on the final result. Nothing crazy, just a bit of shape and color at the right place.

Changing the vibe

One of the greatest leverages of Once UI is the ability to change the entire "vibe" of the app via keywords, without touching the actual code. You can do this inside the once-ui.config.js file, or simply prompt AI to create a different version.
Theme variations of the same app
You can experiment with several pre-defined styles to find the one that best matches your brand, or use our brand tool to create your custom theme.
// Add these at the top of the file
import { Header } from '@/components/Header';
import { Footer } from '@/components/Footer';

// Then render the Header component directly above {children}
// and the Footer component directly below it.
<Column fillWidth center padding="l">
    <Column maxWidth="xl" horizontal="center" gap="48" align="center">
      {/* Text Content Area */}
      <Column maxWidth="m" horizontal="center" gap="24" align="center">
        <RevealFx translateY={2} speed="medium">
          <Heading variant="display-strong-xl" align="center">
            The Design OS for Modern Creators
          </Heading>
        </RevealFx>

        <RevealFx translateY={4} delay={0.2} speed="medium">
          <Text variant="heading-default-xl" onBackground="neutral-weak" wrap="balance" align="center">
            Streamline your workflow from wireframe to production. Build high-end interfaces with clarity, speed, and quiet confidence.
          </Text>
        </RevealFx>

        <RevealFx translateY={6} delay={0.4} speed="medium" fitWidth>
          <Button id="get-started" href="#" variant="primary" size="m" weight="default" arrowIcon>
            Get started for free
          </Button>
        </RevealFx>
      </Column>

      {/* Hero Image Section */}
      <RevealFx translateY={8} delay={0.6} speed="slow" fillWidth>
        <Media
          src="/images/og/home.jpg"
          alt="Design System Dashboard Preview"
          border="neutral-alpha-weak"
          background="surface"
          aspectRatio="16/10"
          radius="xl"
          shadow="l"
          fillWidth
        />
      </RevealFx>
    </Column>
</Column>
<Column fillWidth center padding="l">
    <Column maxWidth="l" horizontal="center" gap="48">

      {/* Text Content Area */}
      <Column maxWidth="m" horizontal="center" gap="24" align="center">
        <RevealFx translateY={2} speed="medium">
          <Heading variant="display-strong-xl" align="center">
            The Design OS for Modern Creators
          </Heading>
        </RevealFx>

        <RevealFx translateY={4} delay={0.2} speed="medium">
          <Text variant="heading-default-xl" onBackground="neutral-weak" wrap="balance" align="center">
            Streamline your workflow from wireframe to production. Build high-end interfaces with clarity, speed, and quiet confidence.
          </Text>
        </RevealFx>

        <RevealFx translateY={6} delay={0.4} speed="medium" fitWidth>
          <Button id="get-started" href="#" variant="primary" size="m" weight="default" arrowIcon>
            Get started for free
          </Button>
        </RevealFx>
      </Column>

      {/* Hero Image Section */}
      <RevealFx translateY={8} delay={0.6} speed="slow" fillWidth>
        <Media
          src="/images/og/home.jpg"
          alt="Design System Dashboard Preview"
          border="neutral-alpha-weak"
          background="surface"
          aspectRatio="16/10"
          radius="xl"
          shadow="l"
          fillWidth
        />
      </RevealFx>

      {/* Features Section */}
      <Column fillWidth gap="48" paddingY="128">
        <Column gap="12" paddingX="24">
          <RevealFx translateY={2} speed="medium">
            <Heading variant="display-strong-s">Everything you need to ship faster</Heading>
          </RevealFx>
          <RevealFx translateY={4} delay={0.2} speed="medium">
            <Text variant="body-default-l" onBackground="neutral-weak">Designed by engineers, for designers who want to build.</Text>
          </RevealFx>
        </Column>
        <Grid columns="3" s={{ columns: 1 }} gap="24" fillWidth>
          <RevealFx translateY={8} delay={0.4} speed="medium" fillWidth>
            <Card padding="24" radius="l" border="neutral-alpha-weak" fillWidth>
              <Column gap="16">
                <Icon name="sparkle" size="m" onBackground="brand-medium" />
                <Column gap="8">
                  <Text variant="heading-strong-s">Smart Components</Text>
                  <Text variant="body-default-m" onBackground="neutral-weak">Highly customizable, accessible, and ready to use in any project.</Text>
                </Column>
              </Column>
            </Card>
          </RevealFx>
          <RevealFx translateY={8} delay={0.5} speed="medium" fillWidth>
            <Card padding="24" radius="l" border="neutral-alpha-weak" fillWidth>
              <Column gap="16">
                <Icon name="rocket" size="m" onBackground="accent-medium" />
                <Column gap="8">
                  <Text variant="heading-strong-s">Lightning Fast</Text>
                  <Text variant="body-default-m" onBackground="neutral-weak">Optimized for performance, ensuring your apps are smooth and responsive.</Text>
                </Column>
              </Column>
            </Card>
          </RevealFx>
          <RevealFx translateY={8} delay={0.6} speed="medium" fillWidth>
            <Card padding="24" radius="l" border="neutral-alpha-weak" fillWidth>
              <Column gap="16">
                <Icon name="security" size="m" onBackground="success-medium" />
                <Column gap="8">
                  <Text variant="heading-strong-s">Secure by Default</Text>
                  <Text variant="body-default-m" onBackground="neutral-weak">Built with security best practices to keep your data safe and sound.</Text>
                </Column>
              </Column>
            </Card>
          </RevealFx>
        </Grid>
      </Column>

      {/* Testimonial Section */}
      <RevealFx translateY={8} delay={0.8} speed="medium" fillWidth>
        <Column fillWidth paddingY="128" center>
          <Column paddingX="xl" gap="32" center>
            <Text variant="display-strong-m" align="center">
              "Once UI has completely transformed how our team builds interfaces. It's not just a UI kit; it's a productivity powerhouse."
            </Text>
            <Row gap="16" vertical="center">
              <Avatar src="/trademarks/icon-dark.svg" size="m" />
              <Column gap="4">
                <Text variant="label-strong-m">Sarah Walker</Text>
                <Text variant="body-default-s" onBackground="neutral-weak">Lead Product Designer @DesignCo</Text>
              </Column>
            </Row>
          </Column>
        </Column>
      </RevealFx>

      {/* Pricing Section */}
      <Column fillWidth gap="48" paddingY="128">
        <Column gap="12" paddingX="24">
          <RevealFx translateY={2} speed="medium">
            <Heading variant="display-strong-s">Simple, transparent pricing</Heading>
          </RevealFx>
          <RevealFx translateY={4} delay={0.2} speed="medium">
            <Text variant="body-default-l" onBackground="neutral-weak">Choose the plan that's right for you and start building today.</Text>
          </RevealFx>
        </Column>
        <Row gap="24" fillWidth s={{ direction: "column" }} horizontal="center">
          <RevealFx translateY={8} delay={0.4} speed="medium" fillWidth>
            <Card padding="32" radius="xl" border="neutral-alpha-weak" fillWidth>
              <Column fillWidth gap="24">
                <Column fillWidth gap="8">
                  <Text variant="label-strong-m" onBackground="neutral-weak">Starter</Text>
                  <Row vertical="end" gap="4">
                    <Heading variant="display-strong-m">$0</Heading>
                    <Text variant="body-default-s" onBackground="neutral-weak" marginBottom="4">/mo</Text>
                  </Row>
                </Column>
                <Line background="neutral-alpha-weak" />
                <Column gap="12">
                  <Row gap="8" vertical="center">
                    <Icon name="check" size="s" onBackground="success-medium" />
                    <Text variant="body-default-m">Up to 3 projects</Text>
                  </Row>
                  <Row gap="8" vertical="center">
                    <Icon name="check" size="s" onBackground="success-medium" />
                    <Text variant="body-default-m">Basic components</Text>
                  </Row>
                  <Row gap="8" vertical="center">
                    <Icon name="check" size="s" onBackground="success-medium" />
                    <Text variant="body-default-m">Community support</Text>
                  </Row>
                </Column>
                <Button variant="secondary" size="m" fillWidth>Get Started</Button>
              </Column>
            </Card>
          </RevealFx>
          <RevealFx translateY={8} delay={0.5} speed="medium" fillWidth>
            <Card padding="32" radius="xl" border="brand-alpha-medium" background="brand-medium" fillWidth>
              <Column fillWidth gap="24">
                <Column fillWidth gap="8">
                  <Row horizontal="between" vertical="center">
                    <Text variant="label-strong-m" onBackground="brand-medium">Pro</Text>
                    <Row paddingX="8" paddingY="2" radius="m" background="brand-alpha-weak">
                      <Text variant="label-strong-xs" onBackground="brand-medium">
                        Popular
                      </Text>
                    </Row>
                  </Row>
                  <Row vertical="end" gap="4">
                    <Heading variant="display-strong-m">$49</Heading>
                    <Text variant="body-default-s" onBackground="neutral-weak" marginBottom="4">/mo</Text>
                  </Row>
                </Column>
                <Line background="neutral-alpha-weak" />
                <Column gap="12">
                  <Row gap="8" vertical="center">
                    <Icon name="check" size="s" onBackground="success-medium" />
                    <Text variant="body-default-m">Unlimited projects</Text>
                  </Row>
                  <Row gap="8" vertical="center">
                    <Icon name="check" size="s" onBackground="success-medium" />
                    <Text variant="body-default-m">Advanced components</Text>
                  </Row>
                  <Row gap="8" vertical="center">
                    <Icon name="check" size="s" onBackground="success-medium" />
                    <Text variant="body-default-m">Priority support</Text>
                  </Row>
                  <Row gap="8" vertical="center">
                    <Icon name="check" size="s" onBackground="success-medium" />
                    <Text variant="body-default-m">Custom branding</Text>
                  </Row>
                </Column>
                <Button variant="primary" size="m" fillWidth>Go Pro</Button>
              </Column>
            </Card>
          </RevealFx>
        </Row>
      </Column>
    </Column>
</Column>
<RevealFx translateY={8} delay={0.8} speed="medium" radius="xl" overflow="hidden" fillWidth>
    <Background
      position="absolute"
      left="0"
      top="0"
      fill
      gradient={{ 
        display: true, 
        x: 50,
        y: 100,
        width: 50,
        colorStart: "brand-background-strong",
      }}
    />
    <Column fillWidth paddingY="128" center>
      <Column paddingX="xl" gap="32" center>
        <Text variant="display-strong-m" align="center">
          "Once UI has completely transformed how our team builds interfaces. It's not just a UI kit; it's a productivity powerhouse."
        </Text>
        <Row gap="16" vertical="center">
          <Avatar src="/trademarks/icon-dark.svg" size="m" />
          <Column gap="4">
            <Text variant="label-strong-m">Sarah Walker</Text>
            <Text variant="body-default-s" onBackground="neutral-weak">Lead Product Designer @DesignCo</Text>
          </Column>
        </Row>
      </Column>
    </Column>
</RevealFx>