# Context

URL: /components/context

---

title: Context
description: A compound component system for displaying AI model context window usage, token consumption, and cost estimation.
path: elements/components/context

---

The `Context` component provides a comprehensive view of AI model usage through a compound component system. It displays context window utilization, token consumption breakdown (input, output, reasoning, cache), and cost estimation in an interactive hover card interface.

<Preview path="context" />

## Installation

<ElementsInstaller path="context" />

## Usage

```tsx
import {
    Context,
    ContextTrigger,
    ContextContent,
    ContextContentHeader,
    ContextContentBody,
    ContextContentFooter,
    ContextInputUsage,
    ContextOutputUsage,
    ContextReasoningUsage,
    ContextCacheUsage,
} from "@/components/ai-elements/context";
```

```tsx
<Context
    maxTokens={128000}
    usedTokens={40000}
    usage={{
        inputTokens: 32000,
        outputTokens: 8000,
        totalTokens: 40000,
        cachedInputTokens: 0,
        reasoningTokens: 0,
    }}
    modelId="openai:gpt-4"
>
    <ContextTrigger />
    <ContextContent>
        <ContextContentHeader />
        <ContextContentBody>
            <ContextInputUsage />
            <ContextOutputUsage />
            <ContextReasoningUsage />
            <ContextCacheUsage />
        </ContextContentBody>
        <ContextContentFooter />
    </ContextContent>
</Context>
```

## Features

-   **Compound Component Architecture**: Flexible composition of context display elements
-   **Visual Progress Indicator**: Circular SVG progress ring showing context usage percentage
-   **Token Breakdown**: Detailed view of input, output, reasoning, and cached tokens
-   **Cost Estimation**: Real-time cost calculation using the `tokenlens` library
-   **Intelligent Formatting**: Automatic token count formatting (K, M, B suffixes)
-   **Interactive Hover Card**: Detailed information revealed on hover
-   **Context Provider Pattern**: Clean data flow through React Context API
-   **TypeScript Support**: Full type definitions for all components
-   **Accessible Design**: Proper ARIA labels and semantic HTML
-   **Theme Integration**: Uses currentColor for automatic theme adaptation

## Props

### `<Context />`

<TypeTable
type={{
  maxTokens: {
    description: 'The total context window size in tokens.',
    type: 'number',
  },
  usedTokens: {
    description: 'The number of tokens currently used.',
    type: 'number',
  },
  usage: {
    description: 'Detailed token usage breakdown from the AI SDK (input, output, reasoning, cached tokens).',
    type: 'LanguageModelUsage',
  },
  modelId: {
    description: 'Model identifier for cost calculation (e.g., "openai:gpt-4", "anthropic:claude-3-opus").',
    type: 'ModelId',
  },
  '...props': {
    description: 'Any other props are spread to the HoverCard component.',
    type: 'ComponentProps<HoverCard>',
  },
}}
/>

### `<ContextTrigger />`

<TypeTable
type={{
  children: {
    description: 'Custom trigger element. If not provided, renders a default button with percentage and icon.',
    type: 'React.ReactNode',
  },
  '...props': {
    description: 'Props spread to the default button element.',
    type: 'ComponentProps<Button>',
  },
}}
/>

### `<ContextContent />`

<TypeTable
type={{
  className: {
    description: 'Additional CSS classes for the hover card content.',
    type: 'string',
  },
  '...props': {
    description: 'Props spread to the HoverCardContent component.',
    type: 'ComponentProps<HoverCardContent>',
  },
}}
/>

### `<ContextContentHeader />`

<TypeTable
type={{
  children: {
    description: 'Custom header content. If not provided, renders percentage and token count with progress bar.',
    type: 'React.ReactNode',
  },
  '...props': {
    description: 'Props spread to the header div element.',
    type: 'ComponentProps<div>',
  },
}}
/>

### `<ContextContentBody />`

<TypeTable
type={{
  children: {
    description: 'Body content, typically containing usage breakdown components.',
    type: 'React.ReactNode',
  },
  '...props': {
    description: 'Props spread to the body div element.',
    type: 'ComponentProps<div>',
  },
}}
/>

### `<ContextContentFooter />`

<TypeTable
type={{
  children: {
    description: 'Custom footer content. If not provided, renders total cost when modelId is provided.',
    type: 'React.ReactNode',
  },
  '...props': {
    description: 'Props spread to the footer div element.',
    type: 'ComponentProps<div>',
  },
}}
/>

### Usage Components

All usage components (`ContextInputUsage`, `ContextOutputUsage`, `ContextReasoningUsage`, `ContextCacheUsage`) share the same props:

<TypeTable
type={{
  children: {
    description: 'Custom content. If not provided, renders token count and cost for the respective usage type.',
    type: 'React.ReactNode',
  },
  className: {
    description: 'Additional CSS classes.',
    type: 'string',
  },
  '...props': {
    description: 'Props spread to the div element.',
    type: 'ComponentProps<div>',
  },
}}
/>

## Component Architecture

The Context component uses a compound component pattern with React Context for data sharing:

1. **`<Context>`** - Root provider component that holds all context data
2. **`<ContextTrigger>`** - Interactive trigger element (default: button with percentage)
3. **`<ContextContent>`** - Hover card content container
4. **`<ContextContentHeader>`** - Header section with progress visualization
5. **`<ContextContentBody>`** - Body section for usage breakdowns
6. **`<ContextContentFooter>`** - Footer section for total cost
7. **Usage Components** - Individual token usage displays (Input, Output, Reasoning, Cache)

## Token Formatting

The component uses `Intl.NumberFormat` with compact notation for automatic formatting:

-   Under 1,000: Shows exact count (e.g., "842")
-   1,000+: Shows with K suffix (e.g., "32K")
-   1,000,000+: Shows with M suffix (e.g., "1.5M")
-   1,000,000,000+: Shows with B suffix (e.g., "2.1B")

## Cost Calculation

When a `modelId` is provided, the component automatically calculates costs using the `tokenlens` library:

-   **Input tokens**: Cost based on model's input pricing
-   **Output tokens**: Cost based on model's output pricing
-   **Reasoning tokens**: Special pricing for reasoning-capable models
-   **Cached tokens**: Reduced pricing for cached input tokens
-   **Total cost**: Sum of all token type costs

Costs are formatted using `Intl.NumberFormat` with USD currency.

## Styling

The component uses Tailwind CSS classes and follows your design system:

-   Progress indicator uses `currentColor` for theme adaptation
-   Hover card has customizable width and padding
-   Footer has a secondary background for visual separation
-   All text sizes use the `text-xs` class for consistency
-   Muted foreground colors for secondary information