gh-nathanonn-claude-skills-ai-elements-claude-skills-ai-elements/docs/components/context.md

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.

Installation

Usage

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

<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', }, }} />

<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', }, }} />

<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', }, }} />

<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

', }, }} />

<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

', }, }} />

<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

', }, }} />

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

', }, }} />

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