Once UI Handbook
Vibe coding
Introduction to vibe coding
Set up your local dev environment
Essential tools for vibe coding
Build your first Once UI app
Getting started
What is Once UI?
Install & config
Page skeleton
Your first page
Upgrade from 1.8 to 2.0
Once UI without Next.js
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
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
Forms that wire themselves
An icon rail that opens on hover
Maps without an API key
Segmented controls that slide
One EmptyState for every blank screen
A globe and 3D buildings in two props
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
Border radius & nested corners
Bring your own icons
Give one section its own style
Override Once UI styles without !important
A logo before you have one
Agent resources
Column, not Flex
Semantics over CSS
Typography scale
Common gotchas
Block anchors
Validate generated code
Pro block registry
Match task bundles
Block updates
Block updates changelog
TrademarkTrademark
Ctrl k
Search…
Sign up
Once UI Handbook
Vibe coding
Introduction to vibe coding
Set up your local dev environment
Essential tools for vibe coding
Build your first Once UI app
Getting started
What is Once UI?
Install & config
Page skeleton
Your first page
Upgrade from 1.8 to 2.0
Once UI without Next.js
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
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
Forms that wire themselves
An icon rail that opens on hover
Maps without an API key
Segmented controls that slide
One EmptyState for every blank screen
A globe and 3D buildings in two props
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
Border radius & nested corners
Bring your own icons
Give one section its own style
Override Once UI styles without !important
A logo before you have one
Agent resources
Column, not Flex
Semantics over CSS
Typography scale
Common gotchas
Block anchors
Validate generated code
Pro block registry
Match task bundles
Block updates
Block updates changelog
TrademarkTrademark
Once UIDocumentationBlog
© Once UI. All rights reserved.
Built with Aveiro
Common Patterns

A globe and 3D buildings in two props

How to turn Once UI's Map into a globe when zoomed out and raise the basemap's buildings to their height: the projection and buildings props, camera pitch, theme-aware colours, and how controlled viewport moves travel.
Updated 3 days ago
One EmptyState for every blank screen
3 min · Pattern · Map
From @once-ui-system/core 2.7.0, Map takes projection="globe" and buildings="3d", replacing about 40 lines of MapLibre setup.

What it used to take

The Maps without an API key page covers the flat map: markers, pins, popups and clusters. If you wanted the 3D look on top of that, you reached into onMapLoad, set the projection, added an extrusion layer for buildings, picked colours that worked in light and dark, and repainted them when the theme changed. Roughly 40 lines of MapLibre code for every app that wanted it. In 2.7.0 that is two props on Map.

The two props

import { Map } from "@once-ui-system/core/map";

<Map
  height={32}
  projection="globe"
  buildings="3d"
  defaultViewport={{ center: [19.0457, 47.507], zoom: 15.5, pitch: 60, bearing: -20 }}
  labels={{ map: "Budapest Parliament" }}
/>
  • projection="globe" curves the world into a globe when you zoom out and flattens it as you zoom in. MapLibre's default blue atmosphere is switched off, because it ignores your theme. The default is "mercator".
  • buildings="3d" extrudes the basemap's own buildings from zoom 13 and hides the flat footprints. The default is "flat".
Both types are exported from /map as and , if you want to pass them around.
MapProjection
MapBuildings

Tilt the camera, or you won't see them

Buildings are extruded straight up, so from directly above they look the same as flat ones. Give the viewport a pitch (60 is a good start) and, if you like, a bearing to turn the street grid. Both sit on MapViewport next to center and zoom, and both default to 0.
Zoom matters too: below 13 there are no 3D buildings at all, so a city overview at zoom 11 stays flat on purpose.

Colours follow the theme

You don't pick colours for the buildings. Low ones use the neutral surface, mid-height ones --brand-background-strong, and the tallest --brand-on-background-weak. The brand-hue tokens are used because the solid tokens can be plain white or black, which would wash out the skyline. They are repainted on every theme change and style swap, and the layer sits above roads and water but below labels, so street names stay readable.

Moving between places

With a controlled viewport, a jump of more than about a degree now flies out and back in (capped at 4 seconds) instead of a short glide. Combined with the globe, a move from Budapest to Lisbon reads as a journey rather than a teleport. With reduced motion turned on it is still instant.
"use client";

import { useState } from "react";
import { Button } from "@once-ui-system/core";
import { Map, type MapViewport } from "@once-ui-system/core/map";

const BUDAPEST: MapViewport = { center: [19.0457, 47.507], zoom: 15.5, pitch: 60, bearing: -20 };
const LISBON: MapViewport = { center: [-9.1393, 38.7223], zoom: 15, pitch: 60 };

export function CityHop() {
  const [viewport, setViewport] = useState<MapViewport>(BUDAPEST);

  return (
    <>
      <Button onClick={() => setViewport(viewport === BUDAPEST ? LISBON : BUDAPEST)}>Switch city</Button>
      <Map height={32} projection="globe" buildings="3d" viewport={viewport} onViewportChange={setViewport} />
    </>
  );
}

When to leave it flat

The globe and 3D buildings are for maps people look at: a venue page, a city guide, a hero. For a map people work with, such as search results with pins and a list beside it, flat usually reads faster, and pins don't get hidden behind towers. Both props default to off for that reason, so turn them on where the view is the point.
More patterns live in this section.
Once UI HandbookPractical guides for building with Once UI. Start with an idea, learn the foundations, and ship your next app.