@ainativekit/ui

🧩 AINativeKit UI - ChatGPT Apps SDK Extension

Production-ready pattern components for ChatGPT Apps

100% compatible with @openai/apps-sdk-ui. Use their primitives + our patterns = ship faster.

Why @ainativekit/ui?

Without this library	With @ainativekit/ui
Build card layouts from scratch	<SummaryCard {...data} />
Wire up carousels manually	<Carousel>{items}</Carousel>
Create map components yourself	<CompactMap locations={...} />
Write ChatGPT integration hooks	useTheme(), useDisplayMode(), useWidgetState()

Fully compatible with apps-sdk-ui - use their 700+ icons, buttons, badges, and design tokens alongside our pattern components.

Architecture

┌─────────────────────────────────────────┐
│           Your ChatGPT App              │
├─────────────────────────────────────────┤
│  @ainativekit/ui (Pattern Components)   │
│  Card, Album, Carousel, List, Map       │
├─────────────────────────────────────────┤
│  @openai/apps-sdk-ui (Primitives)       │
│  Button, Badge, Icon, Alert, Avatar     │
└─────────────────────────────────────────┘

What's Included

Category	Components
Cards	Card, SummaryCard, ImageCard, ListCard
Media	Album, Carousel, PhotoCarousel
Lists	List, ListItem, AvatarList
Maps	CompactMap, FullscreenMap, MapPlaceCard
Feedback	Modal, Sidebar, Skeleton, Overlay
ChatGPT Hooks	useTheme, useDisplayMode, useMaxHeight, useWidgetState

Quick Start

Install

npm install @ainativekit/ui @openai/apps-sdk-ui

Setup

import '@openai/apps-sdk-ui/css';
import '@ainativekit/ui/styles';

Use

import { SummaryCard } from '@ainativekit/ui';
import { StarFilled, Clock } from '@openai/apps-sdk-ui/components/Icon';

function RestaurantCard({ data }) {
  return (
    <SummaryCard
      images={data.images}
      title={data.name}
      subtitle={data.address}
      badge={data.rating}
      description={data.description}
      metadata={[
        { icon: <StarFilled />, label: data.rating },
        { icon: <Clock />, label: 'Open now' }
      ]}
      buttonText="Reserve"
      onButtonClick={() => {}}
    />
  );
}

Components

Cards

import { Card, SummaryCard, ImageCard, ListCard } from '@ainativekit/ui';

// Compound card for custom layouts
<Card elevationLevel={1} interactive>
  <Card.Image src="..." />
  <Card.Body>
    <Card.Title>Title</Card.Title>
    <Card.Description>Description</Card.Description>
  </Card.Body>
  <Card.Footer>
    <Card.ActionButton>Action</Card.ActionButton>
  </Card.Footer>
</Card>

// Pre-composed cards
<SummaryCard images={...} title="..." description="..." />
<ImageCard images={...} title="..." />
<ListCard items={...} />

Carousel

import { Carousel } from '@ainativekit/ui';

<Carousel>
  {items.map(item => (
    <SummaryCard key={item.id} {...item} />
  ))}
</Carousel>

List

import { List, ListItem } from '@ainativekit/ui';
import { StarFilled } from '@openai/apps-sdk-ui/components/Icon';

<List
  header={{ title: 'Top Places', subtitle: 'Based on ratings' }}
  items={places}
  renderItem={(place, index) => (
    <ListItem
      rank={index + 1}
      title={place.name}
      metadata={place.city}
      media={place.thumbnail}
      features={[{ icon: <StarFilled />, label: place.rating }]}
    />
  )}
/>

Album

import { Album } from '@ainativekit/ui';

<Album
  albums={[
    {
      id: '1',
      title: 'Photos',
      cover: '...',
      photos: [{ id: '1', url: '...', title: '...' }]
    }
  ]}
  onAlbumSelect={setSelectedAlbum}
  selectedAlbum={selectedAlbum}
/>

Map

import { CompactMap } from '@ainativekit/ui';
import { StarFilled } from '@openai/apps-sdk-ui/components/Icon';

<CompactMap
  locations={[
    {
      id: '1',
      name: 'Restaurant',
      coords: [37.7749, -122.4194],
      features: [{ icon: <StarFilled />, label: '4.8' }]
    }
  ]}
  onLocationSelect={setSelected}
/>

ChatGPT Hooks

Hooks for integrating with the ChatGPT Apps SDK runtime - these are unique to @ainativekit/ui:

import {
  useTheme,
  useDisplayMode,
  useMaxHeight,
  useWidgetState,
  useOpenAiGlobal,
} from '@ainativekit/ui';

function MyWidget() {
  const { theme } = useTheme();                    // 'light' | 'dark'
  const displayMode = useDisplayMode();            // 'inline' | 'pip' | 'fullscreen'
  const maxHeight = useMaxHeight();                // number | null
  const [state, setState] = useWidgetState(() => ({ count: 0 }));

  return (
    <div style={{ maxHeight: maxHeight ?? 600 }}>
      {/* widget content */}
    </div>
  );
}

Hook	Description
useTheme()	Get current theme from ChatGPT
useDisplayMode()	Get display mode (inline/pip/fullscreen)
useMaxHeight()	Get max height constraint
useWidgetState()	Persistent state across re-renders
useWidgetProps()	Access tool input/output
useOpenAiGlobal(key)	Access any window.openai property

Using apps-sdk-ui Primitives

Icons, buttons, and other primitives come from @openai/apps-sdk-ui:

// 700+ Icons
import { StarFilled, Clock, MapPin } from '@openai/apps-sdk-ui/components/Icon';

// Buttons (also re-exported from @ainativekit/ui)
import { Button } from '@openai/apps-sdk-ui/components/Button';

// Badges (also re-exported from @ainativekit/ui)
import { Badge } from '@openai/apps-sdk-ui/components/Badge';

// Breakpoints hook
import { useBreakpoint } from '@openai/apps-sdk-ui/hooks/useBreakpoints';

TypeScript

Full TypeScript support with window.openai types:

import type { Theme, DisplayMode, LocationData } from '@ainativekit/ui';

// window.openai is fully typed when you import @ainativekit/ui
const theme = window.openai?.theme; // 'light' | 'dark' | undefined

Links

• Live Storybook - Interactive examples
• GitHub
• apps-sdk-ui - Base primitives

License

MIT