Live Activity

Keep an ongoing task visible in a compact surface that expands into consumer-defined details and actions. Use it for deliveries, media playback, recordings, exports, or any persistent process.

Preview

Reduce motion:Off

Tune:Off

Inspect

Tap to expand. On touch devices, drag down to open.

The delivery example connects its identity, status, and ETA across both layouts while the surrounding content is completely consumer-defined.

Installation

Motion

npx shadcn@latest add @sona-ui/live-activity

More examples

Music playback

Rich media, progress, and playback controls can occupy the same reusable surface without introducing media-specific props to the component.

Reduce motion:Off

Tune:Off

Inspect

Tap to expand. On touch devices, drag down to open.

Recording session

The compact view preserves elapsed time and recording state. The expanded view adds a waveform and task-specific controls, with a start-aligned layout to demonstrate a different anchor.

Reduce motion:Off

Tune:Off

Inspect

Tap to expand. On touch devices, drag down to open.

Usage


"use client";
 
import {
  Check,
  MapPin,
  MessageCircle,
  Navigation,
  PackageCheck,
  Truck,
} from "lucide-react";
import { useState } from "react";
import LiveActivity, {
  type LiveActivityProps,
} from "@/components/ui/live-activity/live-activity";
 
type DeliveryState = "moving" | "arriving" | "delivered";
 
const deliveryCopy: Record<
  DeliveryState,
  { title: string; detail: string; eta: string; progress: string }
> = {
  moving: {
    title: "On the way",
    detail: "Maya picked up your order",
    eta: "12 min",
    progress: "72%",
  },
  arriving: {
    title: "Almost there",
    detail: "Maya is approaching your address",
    eta: "2 min",
    progress: "94%",
  },
  delivered: {
    title: "Delivered",
    detail: "Left safely at your front door",
    eta: "Now",
    progress: "100%",
  },
};
 
export function LiveActivityExample({
  direction = "down",
  align = "center",
  gestures = "touch",
  motion = "auto",
}: Pick<LiveActivityProps, "direction" | "align" | "gestures" | "motion">) {
  const [deliveryState, setDeliveryState] = useState<DeliveryState>("moving");
  const copy = deliveryCopy[deliveryState];
  const delivered = deliveryState === "delivered";
 
  const advanceDelivery = () => {
    setDeliveryState((current) =>
      current === "moving"
        ? "arriving"
        : current === "arriving"
          ? "delivered"
          : "moving",
    );
  };
 
  return (
    <div className="flex min-h-[30rem] w-full max-w-xl flex-col items-center justify-between gap-8 px-3 py-10">
      {direction === "up" && <div className="flex-1" />}
      <LiveActivity.Root
        direction={direction}
        align={align}
        gestures={gestures}
        motion={motion}
      >
        <LiveActivity.Surface className="smooth-shadow-ring-lg rounded-[1.75rem] bg-zinc-950 text-white shadow-black/20">
          <LiveActivity.Compact>
            <LiveActivity.Trigger className="flex h-[4.5rem] w-[19rem] items-center gap-3 rounded-[1.75rem] px-3 text-left">
              <LiveActivity.Shared id="courier">
                <span className="flex size-11 items-center justify-center rounded-2xl bg-amber-300 text-zinc-950">
                  {delivered ? (
                    <PackageCheck aria-hidden="true" className="size-5" />
                  ) : (
                    <Truck aria-hidden="true" className="size-5" />
                  )}
                </span>
              </LiveActivity.Shared>
              <span className="min-w-0 flex-1">
                <LiveActivity.Shared
                  id="delivery-title"
                  className="block font-medium tracking-[-0.01em]"
                >
                  {copy.title}
                </LiveActivity.Shared>
                <span className="mt-0.5 block truncate text-xs text-zinc-400">
                  Order #4821
                </span>
              </span>
              <LiveActivity.Shared id="delivery-eta" className="text-right">
                <span className="block text-sm font-semibold tabular-nums">
                  {copy.eta}
                </span>
                <span className="mt-0.5 block text-[0.625rem] font-medium uppercase tracking-[0.12em] text-zinc-500">
                  {delivered ? "status" : "away"}
                </span>
              </LiveActivity.Shared>
            </LiveActivity.Trigger>
          </LiveActivity.Compact>
 
          <LiveActivity.Expanded className="w-[22rem] p-4 pb-4 [@media(pointer:coarse)]:pb-0">
            <div className="flex items-center gap-3">
              <LiveActivity.Shared id="courier">
                <span className="flex size-11 items-center justify-center rounded-2xl bg-amber-300 text-zinc-950">
                  {delivered ? (
                    <PackageCheck aria-hidden="true" className="size-5" />
                  ) : (
                    <Truck aria-hidden="true" className="size-5" />
                  )}
                </span>
              </LiveActivity.Shared>
              <span className="min-w-0 flex-1">
                <LiveActivity.Shared
                  id="delivery-title"
                  className="block font-medium tracking-[-0.01em]"
                >
                  {copy.title}
                </LiveActivity.Shared>
                <span className="mt-0.5 block text-xs text-zinc-400">
                  {copy.detail}
                </span>
              </span>
              <LiveActivity.Shared id="delivery-eta" className="text-right">
                <span className="block text-sm font-semibold tabular-nums">
                  {copy.eta}
                </span>
                <span className="mt-0.5 block text-[0.625rem] font-medium uppercase tracking-[0.12em] text-zinc-500">
                  {delivered ? "status" : "away"}
                </span>
              </LiveActivity.Shared>
              <LiveActivity.Close className="flex size-9 shrink-0 items-center justify-center rounded-full text-lg text-zinc-500 hover:bg-white/10 hover:text-white" />
            </div>
 
            <div className="relative mt-4 overflow-hidden rounded-2xl bg-zinc-900 px-4 py-5">
              <div
                aria-hidden="true"
                className="absolute inset-0 opacity-25 [background-image:linear-gradient(to_right,theme(colors.zinc.700)_1px,transparent_1px),linear-gradient(to_bottom,theme(colors.zinc.700)_1px,transparent_1px)] [background-size:24px_24px]"
              />
              <div className="relative flex items-center gap-3">
                <span className="flex size-9 items-center justify-center rounded-full bg-white text-zinc-950 shadow-lg shadow-black/30">
                  <Truck aria-hidden="true" className="size-4" />
                </span>
                <span className="h-1 flex-1 overflow-hidden rounded-full bg-white/10">
                  <span
                    className="block h-full origin-left rounded-full bg-amber-300 transition-transform duration-300 motion-reduce:transition-none"
                    style={{
                      transform: `scaleX(${Number.parseInt(copy.progress, 10) / 100})`,
                    }}
                  />
                </span>
                <span className="flex size-9 items-center justify-center rounded-full bg-amber-300 text-zinc-950 shadow-lg shadow-amber-300/10">
                  {delivered ? (
                    <Check aria-hidden="true" className="size-4" />
                  ) : (
                    <MapPin aria-hidden="true" className="size-4" />
                  )}
                </span>
              </div>
              <div className="relative mt-4 flex items-end justify-between text-xs">
                <span className="text-zinc-400">Green Street Kitchen</span>
                <span className="font-medium text-zinc-200">Home</span>
              </div>
            </div>
 
            <div className="mt-3 grid grid-cols-2 gap-2">
              <button
                type="button"
                className="flex min-h-11 items-center justify-center gap-2 rounded-xl bg-zinc-900 text-sm font-medium text-zinc-200 transition-colors hover:bg-zinc-800 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-amber-300 active:scale-[0.98] motion-reduce:transform-none"
              >
                <MessageCircle aria-hidden="true" className="size-4" />
                Message
              </button>
              <button
                type="button"
                className="flex min-h-11 items-center justify-center gap-2 rounded-xl bg-amber-300 text-sm font-semibold text-zinc-950 transition-colors hover:bg-amber-200 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-amber-300 active:scale-[0.98] motion-reduce:transform-none"
              >
                <Navigation aria-hidden="true" className="size-4" />
                Track order
              </button>
            </div>
            <LiveActivity.Handle className="mt-1 text-zinc-500 hover:text-zinc-300" />
          </LiveActivity.Expanded>
        </LiveActivity.Surface>
      </LiveActivity.Root>
 
      <div className="flex flex-col items-center gap-2 text-center">
        <button
          type="button"
          onClick={advanceDelivery}
          className="rounded-full bg-muted px-4 py-2 text-xs font-medium text-foreground transition-colors hover:bg-muted/70 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring"
        >
          {delivered ? "Restart delivery" : "Advance delivery"}
        </button>
        <p className="text-xs text-muted-foreground">
          Tap to expand. On touch devices, drag down to open.
        </p>
      </div>
      <span role="status" className="sr-only">
        {copy.title}. {copy.detail}.
      </span>
    </div>
  );
}
 
export default function LiveActivityDemo() {
  return <LiveActivityExample />;
}

Composition

Root owns expansion and touch interaction. Place one Surface inside it, containing one Compact and one Expanded view. Put a Trigger in the compact view and a Close or Handle in the expanded view. These controls render native buttons; do not nest other buttons or links inside a trigger.

Shared renders an inline-block span. Give corresponding visual elements the same id in each view. IDs are scoped to their Root. Use one occurrence of an ID per view and avoid nested Shared elements. The component translates each pair between its measured positions and cross-fades the two representations without scaling text. Unmatched elements cross-fade with their view.

Both views remain mounted for measurement. The inactive view is inert and hidden from assistive technology. Each view has its own React subtree, so two copies of an input or video do not share an instance. Lift shared state to the consumer and use unique DOM IDs in each view. Avoid auto-playing media and side effects in hidden content.

Layout and styling

Size each view with className or style, such as className="w-80 p-5" on Expanded. Keep padding on the views and apply background, radius, and elevation to Surface. Avoid percentage-based view widths: use a fixed or intrinsic width, which is capped to the Root's available width.

Root reserves the compact height. The surface overlays the surrounding layout as it expands. Give its parent enough clear space, or position Root in your application's floating layer. This component does not provide a portal, viewport collision detection, or automatic placement. Avoid clipping ancestors.

direction="down" preserves the top edge; direction="up" preserves the bottom edge. align="start", "center", or "end" sets the horizontal anchor. Direction also reverses the opening and closing touch gestures. Choose a direction with enough room for the expanded content.

Touch and keyboard

Touch dragging starts on Trigger or Handle. Drag toward the expansion direction to open and in the opposite direction to collapse. The surface follows the finger and settles after release. Cancellation restores the accepted state. Mouse input uses buttons; expanded content retains its normal scrolling and interactions.

The bottom Handle is rendered as a mobile touch affordance. It is hidden on fine-pointer devices, while Close remains available for desktop mouse and keyboard users.

When using a mobile-only handle, keep the expanded view's bottom padding conditional: reserve it for fine-pointer layouts and let the handle provide the mobile inset.

Enter and Space activate the buttons. Escape collapses when focus is inside the activity. If focus was inside the outgoing view, it moves into the incoming view; external updates do not pull focus from elsewhere. Keep an explicit collapse control even when gestures are enabled.

API

Property	Type	Default	Description
`children`	`ReactNode`	`required`	The composed activity surface and views.
`expanded`	`boolean`	`undefined`	Controlled expansion state.
`defaultExpanded`	`boolean`	`false`	Initial uncontrolled expansion state.
`onExpandedChange`	`(expanded: boolean) => void`	`undefined`	Called when a control or gesture requests a state change.
`direction`	`"down" \| "up"`	`"down"`	Direction of growth and the opening touch gesture.
`align`	`"start" \| "center" \| "end"`	`"center"`	Horizontal edge or center kept anchored during resizing.
`gestures`	`"touch" \| false`	`"touch"`	Enable touch dragging on Trigger and Handle, or disable gestures.
`motion`	`"auto" \| "none"`	`"auto"`	Respect reduced motion automatically, or disable all transitions.

Accessibility and motion

Native controls expose expansion state and reference the expanded panel. Consumers provide meaningful activity labels, progress semantics, and polite announcements for meaningful status changes. Avoid announcing every percentage tick. The demo deliberately uses manual lifecycle controls rather than implying a real export is running.

Reduced motion and motion="none" apply state changes immediately while preserving gestures and controls. Keyboard activation also switches immediately. One interruptible progress value coordinates the shell, view opacity, and shared positions. The shell animates measured dimensions to preserve text shape; content itself is not scaled.

When content changes the measured width or height of the active view, the shell retargets its spring from the current rendered size. A new gesture interrupts that resize animation and immediately restores direct touch tracking.

Was this page helpful?

Your response helps us improve component docs.