Overview

Updated: Sep 24, 2026
Choose the semantic component that matches the interface’s purpose. Semantic components own the expected layout, focus behavior, accessibility, material, and motion; use Foundation primitives only when no semantic component fits.
This page helps you choose between components. For props and examples, follow the links to the individual component pages or browse the Foundation overview and Meta Ray-Ban Display component catalog.

Choose a component

Routes and navigation

You needUse
The application shell, once at the root
App
A route with a standard header
Page
A route with swipeable sibling sections
SubNavigationPager
Animated transitions between routes
PageTransition
A generic multi-page container within a route
Pager
Position within a pager or carousel
PaginationIndicator

Content and collections

You needUse
A vertical list of rows
VerticalList with ListItem
Another scrolling region
ScrollView
Horizontal browsing between destinations
Carousel
An activatable media or artwork block
Card
A stacked set of cards
CardStack
Icon actions revealed by swiping a row
SwipeToReveal

Actions and choices

You needUse
One clear action
Button
Overflowing horizontal actions
ButtonRail
A small set of actions that fits
ButtonGroup
A compact messaging reply
QuickReplyButton
Free-form text entry
InputTextView
A toggle, radio choice, or slider in a row
ListItem with its built-in control
A standalone adjustable value
SliderBar or IsolatedControl
Media playback position
Scrubber
A square control or launcher tile
ControlTile or AppControlTile
Manifest-themed Web App identity
WebAppIcon

Feedback and overlays

You needUse
Structured decision or informational content in a route
Modal
Transient outcome feedback
Toast
A hint attached to a focused element
Built-in tooltip props or Tooltip
An anchored action menu
ContextMenu
An anchored text-first menu
VerticalMenu
Legibility over media
Scrim or Vignette

Progress and status

You needUse
Linear determinate progress
ProgressIndicator
Circular determinate progress
ProgressRing or CircularProgressBar
Unknown-duration progress
IndeterminateLoader
A loading skeleton
Shimmer
A system-style value overlay
VolumeIndicator or ZoomIndicator
A short input affordance
ActionHint

Identity, labels, and text

You needUse
A person or entity image
Avatar
A minimal status label
Tag
A richer label with metadata or an icon
Chip
Body or heading text
TextView
Text that crossfades when it changes
TextSwitcher
Long text that must clamp and expand
ReadMoreTextView

Common decisions

Page or SubNavigationPager?

Use Page for a normal route with one content area. Use SubNavigationPager when the route contains sibling sections that users move between. They are alternative route roots; do not combine them.

VerticalList or ScrollView?

Use VerticalList for a column of rows, usually ListItem components. Use ScrollView for other scrolling content. Keep one same-axis scroll owner per route so focus and directional navigation remain predictable.

ButtonRail or ButtonGroup?

Use ButtonRail when actions can overflow, need horizontal scrolling, or form a bottom action surface. Use ButtonGroup when a small set fits and should remain together, such as actions in a Modal.

Toast, tooltip, menu, or modal?

  • Use Toast for transient outcome feedback that requires no action.
  • Use Tooltip to explain a focused control.
  • Use ContextMenu or VerticalMenu for actions anchored to an element.
  • Use Modal for structured content within a route. It is an inline panel, not a blocking overlay; prefer a dedicated route for a blocking decision.

Semantic component or Foundation primitive?

Prefer the semantic component. If none fits, use Container for an interactable material surface, StaticContainer for a non-interactive one, or InteractableBase for interaction behavior without material. Do not recreate an existing component from generic elements or override its internal anatomy.

Cross-component rules

  • Render exactly one App at the application root. It owns global focus, toast, and portal infrastructure.
  • Let Page own the route header and its relationship to content. Do not place a standalone Header in route content.
  • Use one scrolling owner per axis and route. Avoid nesting VerticalList inside ScrollView.
  • Use component-provided icon slots and pass an IconSource; the host component owns icon size, placement, and tint. See Icons.
  • Render anchored surfaces through the portal infrastructure supplied by App so they remain aligned with their owners.
  • Keep component internals intact. Customize through documented props, semantic tokens, and supported composition points.