Flight Status

When to useCopy Anchor Link

• The user asks about a flight's live status: is it on time, has it landed, where is it now, which gate or baggage belt.
• The agent has the status from a flight-data tool result.

When not to useCopy Anchor Link

• The agent doesn't have live data from a tool result. Never guess states, gates or times.
• The user wants their booking details, seat or boarding pass. Use Flight Ticket.
• The user is comparing flights to book.

How the agent should use itCopy Anchor Link

• Pass times with the airport's UTC offset and IANA timezone, exactly as the source gives them. Don't convert them.
• Pass scheduled, estimated and actual times as reported. The component works out the delay, the remaining time and the "On time" marks.
• List updates newest first, in the source's words.
• Only set watch when you can actually notify the user. On watch, subscribe them and confirm in text.
• For live tracking, re-render the same component with new props instead of calling the tool again.

What it showsCopy Anchor Link

• Header: flight number and airline, one quiet line with the cities and date, and a state badge with its own icon and label: "Delayed", "Cancelled" (destructive), "Diverted to OPO". Nothing relies on color alone.
• Departure and arrival: the airport code, then the time in large type in each airport's zone. A changed time shows the schedule struck through next to the new one. Under each end, "On time", "Delayed 45 min" or "11 min early". Within 5 minutes counts as on time. A +1 marks an arrival on a later calendar day.
• Progress bar: a dot at the origin, a ring at the destination, and a plane at the fill edge. Progress comes from progress while in the air, or from elapsed time over the expected flight time; it's 0 before departure and 1 once landed. Under it, one relative line: "Departs in 1 h 29 min", "Arrives in 2 h 52 min", "Landed 12 min ago".
• Details: terminals and gates at both ends, baggage belt, and altitude and ground speed while in the air.
• Footer: the update time and source, and the "Notify me of changes" action when watch is set.
• Screen readers only: the flight time, delayReason, the user's seat and class, and the list of updates. The update times use the departure airport's zone before take-off and the arrival airport's after, as does the footer time.

Times and timezonesCopy Anchor Link

Every time shows in its airport's own timezone on a 24-hour clock. Screen readers hear the date, city and offset: "Departs, estimated Thursday, October 8, 14:05 London time (GMT+1), scheduled 13:20". Formatting uses Intl only; the helpers are in flight-status-utils.ts (effectiveTime, stateDelay, deriveProgress, relativeText, …).

Relative text is computed after mount and refreshed every 30 seconds, so server and client render the same markup. Pass now to measure from a fixed moment instead.

Live updatesCopy Anchor Link

Re-render with new props as the source changes. The plane glides to its new position (a transform, so it's skipped under reduced motion), and changes of state or a new latest update are announced in a polite live region, such as "NW 482: Landed". Nothing is announced on the first render.

InstallationCopy Anchor Link

npx shadcn@latest add https://your-site.com/r/flight-status.json

UsageCopy Anchor Link

import { tool } from "ai"
import { flightStatusTool } from "@/components/genui/flight-status.schema"

const tools = {
  [flightStatusTool.name]: tool({
    description: flightStatusTool.description,
    inputSchema: flightStatusTool.inputSchema,
    // Without `watch` it's display-only, so the tool can return immediately.
    execute: async () => ({ shown: true }),
  }),
}

Render it, refreshing the props from your flight-data feed:

import { FlightStatus } from "@/components/genui/flight-status"

function ToolPart({ part }) {
  if (part.type !== "tool-track_flight") return null
  const live = useLiveFlight(part.input) // your polling or push feed

  return (
    <FlightStatus
      {...live}
      status={part.state === "input-streaming" ? "streaming" : undefined}
      result={savedWatch(part.toolCallId)}
      onResult={(result) => {
        // { action: "watch" }: subscribe the user, then tell the agent.
        subscribeToFlight(part.input.flightNumber)
        sendMessage({ text: `Flight status action: ${JSON.stringify(result)}` })
      }}
    />
  )
}

With watch, the agent receives:

{ action: "watch" }

With LangGraphCopy Anchor Link

Push it from a graph node with ui.push({ name: "track_flight", props: { toolCallId, ...args } }, { message }), and push it again with fresh props as the status changes. Render the thread's UI messages with the Renderer.

Restoring from historyCopy Anchor Link

Pass the stored watch result back as result. The button is replaced by "We'll tell you about changes" and onResult is never called again.

<FlightStatus {...props} result={{ action: "watch" }} />

SchemaCopy Anchor Link

Host props: status (streaming, ready, submitting, watching), now, onResult, result and className.

SourceCopy Anchor Link