API Reference

Complete reference of all exports from @gxp-dev/uikit.

UI Primitives

shadcn-vue components built on reka-ui primitives.

Form Controls

// Basic inputs
import { Input, Textarea, Label } from '@gxp-dev/uikit'

// Selection
import { Checkbox, Switch, RadioGroup, RadioGroupItem } from '@gxp-dev/uikit'
import { Select, SelectContent, SelectGroup, SelectItem, SelectItemText, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue } from '@gxp-dev/uikit'

// Slider
import { Slider } from '@gxp-dev/uikit'

Buttons & Badges

import { Button, buttonVariants, type ButtonVariants } from '@gxp-dev/uikit'
import { Badge, badgeVariants, type BadgeVariants } from '@gxp-dev/uikit'

Layout & Containers

import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from '@gxp-dev/uikit'
import { Separator } from '@gxp-dev/uikit'
import { AspectRatio } from '@gxp-dev/uikit'
import { ScrollArea, ScrollBar } from '@gxp-dev/uikit'
import { Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle, SheetTrigger, sheetVariants, type SheetVariants } from '@gxp-dev/uikit'

Dialogs & Overlays

import { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogScrollContent, DialogTitle, DialogTrigger } from '@gxp-dev/uikit'
import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogTitle, AlertDialogTrigger } from '@gxp-dev/uikit'
import { Popover, PopoverContent, PopoverTrigger } from '@gxp-dev/uikit'
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@gxp-dev/uikit'
import { HoverCard, HoverCardContent, HoverCardTrigger } from '@gxp-dev/uikit'

Menus & Navigation

import { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger } from '@gxp-dev/uikit'
import { ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger } from '@gxp-dev/uikit'
import { Menubar, MenubarCheckboxItem, MenubarContent, MenubarGroup, MenubarItem, MenubarLabel, MenubarMenu, MenubarRadioGroup, MenubarRadioItem, MenubarSeparator, MenubarShortcut, MenubarSub, MenubarSubContent, MenubarSubTrigger, MenubarTrigger } from '@gxp-dev/uikit'
import { NavigationMenu, NavigationMenuContent, NavigationMenuIndicator, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuTrigger, NavigationMenuViewport, navigationMenuTriggerStyle } from '@gxp-dev/uikit'

Tabs & Accordions

import { Tabs, TabsContent, TabsList, TabsTrigger } from '@gxp-dev/uikit'
import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from '@gxp-dev/uikit'
import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@gxp-dev/uikit'

Data Display

import { Table, TableBody, TableCaption, TableCell, TableEmpty, TableFooter, TableHead, TableHeader, TableRow } from '@gxp-dev/uikit'
import { Avatar, AvatarFallback, AvatarImage, avatarVariant, type AvatarVariants } from '@gxp-dev/uikit'
import { Alert, AlertDescription, AlertTitle, alertVariants, type AlertVariants } from '@gxp-dev/uikit'
import { Skeleton } from '@gxp-dev/uikit'
import { Progress } from '@gxp-dev/uikit'

Pagination

import { Pagination, PaginationContent, PaginationEllipsis, PaginationFirst, PaginationItem, PaginationLast, PaginationNext, PaginationPrevious } from '@gxp-dev/uikit'

Forms

import { Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage } from '@gxp-dev/uikit'

Command & Calendar

import { Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut } from '@gxp-dev/uikit'
import { Calendar, CalendarCell, CalendarCellTrigger, CalendarGrid, CalendarGridBody, CalendarGridHead, CalendarGridRow, CalendarHeadCell, CalendarHeader, CalendarHeading, CalendarNextButton, CalendarPrevButton } from '@gxp-dev/uikit'

Toasts

import { Toaster } from '@gxp-dev/uikit'

---

Domain Components

Application-specific components with business logic.

Spinner

Loading spinner with size variants.

import { Spinner, type SpinnerProps } from '@gxp-dev/uikit'

interface SpinnerProps {
  size?: 'sm' | 'md' | 'lg'
  class?: string
}

Header

Branded header with background image/video and logo support.

import { Header, type HeaderProps } from '@gxp-dev/uikit'

interface HeaderProps {
  backgroundImage?: string
  logoImage?: string
  videoSrc?: string
  hideVideo?: boolean
  class?: string
}

Countdown

Inactivity timer that emits event on timeout.

import { Countdown, type CountdownProps } from '@gxp-dev/uikit'

interface CountdownProps {
  timeoutLength?: number  // seconds
  ignoreTimeout?: boolean
  class?: string
}

// Events: 'countdown-completed'

VideoPlayer

Video player with event hooks.

import { VideoPlayer, type VideoPlayerProps } from '@gxp-dev/uikit'

interface VideoPlayerProps {
  src: string
  height?: string
  controls?: boolean
  autoplay?: boolean
  muted?: boolean
  loop?: boolean
  class?: string
}

// Events: 'play', 'pause', 'ended', 'error', 'loadedmetadata'

FileUploader

File upload with image/video support and HEIC conversion.

import { FileUploader, type FileUploaderProps, type FileSelectedPayload } from '@gxp-dev/uikit'

interface FileUploaderProps {
  buttonText?: string
  acceptImages?: boolean
  acceptVideos?: boolean
  multiple?: boolean
  class?: string
}

interface FileSelectedPayload {
  file: File
  type: 'image' | 'video' | 'audio'
  size: number
  name: string
  mimeType: string
}

// Events: 'file-selected', 'file-cleared', 'upload-error', 'upload-started', 'upload-cancelled'

BarcodeScanner

Camera-based barcode scanner using Quagga2.

import { BarcodeScanner, type BarcodeScannerProps } from '@gxp-dev/uikit'

interface BarcodeScannerProps {
  instructions?: string
  backText?: string
  scanButtonText?: string
  autoStart?: boolean
  facingMode?: 'user' | 'environment'
  readers?: string[]  // default: ['code_128_reader']
  class?: string
}

// Events: 'scan', 'error', 'scanner-opened', 'scanner-closed'

Leaderboard

Gamification components for rankings and activity feeds.

import {
  Leaderboard,
  ActivityNotifications,
  AwardIcon,
  type LeaderboardProps,
  type LeaderboardEntry,
  type ActivityNotificationsProps,
  type ActivityItem,
  type AwardIconProps
} from '@gxp-dev/uikit'

AudioVisualizer

Real-time audio visualization in frequency or waveform mode.

import { AudioVisualizer, type AudioVisualizerProps } from '@gxp-dev/uikit'

interface AudioVisualizerProps {
  active?: boolean
  stream?: MediaStream | null
  mode?: 'frequency' | 'waveform'
  waveformData?: number[]
  audioSrc?: string
  timeLimitSeconds?: number
  marksPerSecond?: number
  minHeight?: number
  class?: string
}

// Events: 'ended', 'volume-data'

---

Composables

Reusable composition functions for common patterns.

useMedia

Media device management (camera, microphone, recording).

import { useMedia, type UseMediaReturn } from '@gxp-dev/uikit'

interface UseMediaReturn {
  devices: Ref<MediaDevice[]>
  videoStream: Ref<MediaStream | null>
  videoDeviceId: ComputedRef<string | undefined>
  audioStream: Ref<MediaStream | null>
  audioDeviceId: ComputedRef<string | undefined>
  changingDevice: Ref<boolean>
  videoBlob: Ref<Blob | null>
  videoURL: Ref<string | null>
  audioBlob: Ref<Blob | null>
  audioURL: Ref<string | null>
  audioVolumeWave: Ref<number[]>
  photoBlob: Ref<Blob | null>
  photoURL: Ref<string | null>
  facingMode: ComputedRef<string | undefined>
  currentFacingMode: Ref<string>
  // ... plus methods for device control, recording, photo capture
}

useScanning

Barcode scanner state management.

import { useScanning, type UseScanningReturn } from '@gxp-dev/uikit'

interface UseScanningReturn {
  scanIsOpen: Ref<boolean>
  registeredQuagga: Ref<boolean>
  ocr: Ref<boolean>
  openScanner: () => void
  closeScanner: () => void
  resetScanState: () => void
}

useAnimations

Page transition animations with animate.css support.

import { useAnimations, type UseAnimationsReturn, type AnimationSettings } from '@gxp-dev/uikit'

interface UseAnimationsReturn {
  animatingClasses: ComputedRef<string[]>
  pageAnimation: Ref<string>
  init: (props: { globalSettings?: AnimationSettings }) => void
  animatePage: (vars?: AnimationVars, reverse?: boolean) => Promise<void>
}

useErrors

Global error state management.

import { useErrors, type UseErrorsReturn } from '@gxp-dev/uikit'

interface UseErrorsReturn {
  errorMessages: Ref<string[]>
  addError: (message: string) => void
  removeError: (index: number) => void
  clearErrors: () => void
}

useNfcListener

NFC tag scanning listener (postMessage-based).

import { useNfcListener, simulateNfcScan, type UseNfcListenerReturn, type NfcScanData } from '@gxp-dev/uikit'

interface UseNfcListenerReturn {
  registerHandler: (handler: NfcHandler) => () => void
}

interface NfcScanData {
  uid: string
  tagType: string
  timestamp: number
}

type NfcHandler = (data: NfcScanData) => void

---

Utilities

cn()

Tailwind CSS class merging with conflict resolution.

import { cn } from '@gxp-dev/uikit'

function cn(...inputs: ClassValue[]): string

Image Processing

import { processUploadedImage, convertToCanvasBlob } from '@gxp-dev/uikit'

// HEIC/HEIF conversion and image optimization
async function processUploadedImage(file: File): Promise<Blob>
async function convertToCanvasBlob(canvas: HTMLCanvasElement, type?: string, quality?: number): Promise<Blob>

---

Experience Flow

State-machine orchestrator and 20 prebuilt page components for multi-stage interactive apps. See the Experience Flow guide for the full reference.

Orchestrator

import {
  useExperience,
  ExperienceFlow,
  withExperienceDefaults,
  readExperienceDefaults,
  type UseExperienceReturn,
  type ExperienceFlowConfig,
  type ExperienceFlowProps,
  type ExperiencePageDef,
  type ExperiencePageDefaults,
  type ExperienceContext,
  type ExperienceAction,
  type ExperienceActionFn,
} from '@gxp-dev/uikit'

function useExperience(config: ExperienceFlowConfig): UseExperienceReturn

interface ExperienceFlowConfig {
  pages: ExperiencePageDef[]
  api?: ExperienceApi
  initialContext?: ExperienceContext
  onComplete?: (ctx: ExperienceContext) => void
  onError?: (err: Error, ctx: ExperienceContext) => boolean | void
}

interface ExperiencePageDef {
  name: string
  component: Component
  props?: Record<string, unknown>
  when?: (ctx: ExperienceContext) => boolean
  action?: ExperienceAction       // 'publishPost' | function | false
  resultKey?: string              // defaults to page name
}

interface UseExperienceReturn {
  pages: ComputedRef<ExperiencePageDef[]>
  currentPage: ComputedRef<ExperiencePageDef | null>
  pageName: ComputedRef<string | null>
  index: Ref<number>
  isFirst: ComputedRef<boolean>
  isLast: ComputedRef<boolean>
  context: ExperienceContext
  busy: Ref<boolean>
  error: Ref<Error | null>
  next: (data?: unknown) => Promise<void>
  back: () => void
  goTo: (name: string) => Promise<void>
  reset: () => void
  clearError: () => void
}

API Adapter

import {
  useExperienceApi,
  type ExperienceApi,
  type ExperienceActionName,
  type CallApi,
  type UseExperienceApiOptions,
  type PublishPostInput,
} from '@gxp-dev/uikit'

function useExperienceApi(options: UseExperienceApiOptions): ExperienceApi

interface UseExperienceApiOptions {
  callApi: CallApi
  overrides?: Partial<ExperienceApi>
  endpoints?: Partial<Record<keyof ExperienceApi, string>>
}

type CallApi = <T = unknown>(endpoint: string, payload?: unknown) => Promise<T>

interface ExperienceApi {
  publishPost:      (data: PublishPostInput) => Promise<unknown>
  fetchPost:        (id: string | number, opts?: { include?: string[] }) => Promise<unknown>
  fetchRecentPosts: () => Promise<unknown>
  tagPost:          (id: string | number, tags: unknown[]) => Promise<unknown>
  createPrintJob:   (data: { social_stream_post_id: string | number; access_point_id?: string | number }) => Promise<unknown>
  processImage:     (data: { blob: Blob; prompt?: string; background_remover?: boolean; background_generator?: boolean }) => Promise<unknown>
  refinePrompt:     (prompt: string) => Promise<unknown>
  generateImages:   (data: { prompt: string; count?: number }) => Promise<unknown>
  analyzeSketch:    (data: { blob: Blob }) => Promise<unknown>
  call:             <T = unknown>(endpoint: string, payload?: unknown) => Promise<T>
}

Pages

All pages export both the component and its props/payload types.

// Intro & legal
import { WelcomePage,      type WelcomePageProps }      from '@gxp-dev/uikit'
import { TermsPage,        type TermsPageProps }        from '@gxp-dev/uikit'
import { InstructionsPage, type InstructionsPageProps } from '@gxp-dev/uikit'

// Capture
import { CameraPage,         type CameraPageProps }                                  from '@gxp-dev/uikit'
import { CameraReviewPage,   type CameraReviewPageProps, type CameraReviewPagePayload } from '@gxp-dev/uikit'
import { VideoCapturePage,   type VideoCapturePageProps }                            from '@gxp-dev/uikit'
import { VideoReviewPage,    type VideoReviewPagePayload }                           from '@gxp-dev/uikit'
import { AudioCapturePage,   type AudioCapturePageProps }                            from '@gxp-dev/uikit'
import { AudioReviewPage,    type AudioReviewPagePayload }                           from '@gxp-dev/uikit'
import { DrawingPage,        type DrawingTool }                                      from '@gxp-dev/uikit'
import { NotepadPage,        type NotepadPagePayload }                               from '@gxp-dev/uikit'
import { TextPage,           type TextPageProps }                                    from '@gxp-dev/uikit'
import { PromptPage,         type PromptTemplateToken }                              from '@gxp-dev/uikit'
import { OptionsPage,        type ExperienceOption }                                 from '@gxp-dev/uikit'
import { FormPage,           type FormFieldDef, type FormFieldType, type FormFieldOption } from '@gxp-dev/uikit'

// Outcome
import { ResultsGalleryPage, type GalleryResult }                                    from '@gxp-dev/uikit'
import { PhotoEditPage,      type SubjectOption, type BackdropOption }               from '@gxp-dev/uikit'
import { SharePage,          type SharePageMedia, type ShareAttribution, type ShareMediaType } from '@gxp-dev/uikit'
import { FinalPage,          type FinalPageProps, type FinalActionDescriptor }       from '@gxp-dev/uikit'

// Utility
import { LoadingPage,        type LoadingPageProps, type LoadingTask }               from '@gxp-dev/uikit'

See Pages reference for each page's props, emits, slots, and default action.

---

Types

All component props interfaces and composable return types are exported for TypeScript consumers.

// Component variants
import type {
  ButtonVariants,
  BadgeVariants,
  AlertVariants,
  AvatarVariants,
  SheetVariants
} from '@gxp-dev/uikit'

// Domain component props
import type {
  SpinnerProps,
  HeaderProps,
  CountdownProps,
  VideoPlayerProps,
  FileUploaderProps,
  FileSelectedPayload,
  BarcodeScannerProps,
  LeaderboardProps,
  LeaderboardEntry,
  ActivityNotificationsProps,
  ActivityItem,
  AwardIconProps,
  AudioVisualizerProps,
} from '@gxp-dev/uikit'

// Composable types
import type {
  UseMediaReturn,
  MediaDevice,
  SetDeviceOptions,
  RecordingOptions,
  UseScanningReturn,
  UseAnimationsReturn,
  AnimationSettings,
  UseErrorsReturn,
  UseNfcListenerReturn,
  NfcScanData,
  NfcHandler,
} from '@gxp-dev/uikit'

// Experience flow types
import type {
  // orchestrator
  ExperienceApi,
  ExperienceAction,
  ExperienceActionFn,
  ExperienceActionName,
  ExperienceContext,
  ExperienceFlowConfig,
  ExperienceFlowProps,
  ExperiencePageDef,
  ExperiencePageDefaults,
  UseExperienceReturn,
  // api adapter
  CallApi,
  UseExperienceApiOptions,
  PublishPostInput,
  // page props / payloads
  WelcomePageProps,
  TermsPageProps,
  InstructionsPageProps,
  CameraPageProps,
  CameraReviewPageProps,
  CameraReviewPagePayload,
  VideoCapturePageProps,
  VideoReviewPagePayload,
  AudioCapturePageProps,
  AudioReviewPagePayload,
  DrawingTool,
  NotepadPagePayload,
  TextPageProps,
  PromptTemplateToken,
  ExperienceOption,
  FormFieldDef,
  FormFieldType,
  FormFieldOption,
  GalleryResult,
  BackdropOption,
  SubjectOption,
  SharePageMedia,
  ShareAttribution,
  ShareMediaType,
  LoadingPageProps,
  LoadingTask,
  FinalPageProps,
  FinalActionDescriptor,
} from '@gxp-dev/uikit'

---

Styles

Full Styles

Includes Tailwind base, components, and default theme:

import '@gxp-dev/uikit/styles'

Base Styles

Tailwind base and components without theme:

import '@gxp-dev/uikit/styles/base'

Theme Only

Just the default theme CSS variables:

import '@gxp-dev/uikit/styles/themes/default.css'

---

Version

import { VERSION } from '@gxp-dev/uikit'

console.log(VERSION) // '0.1.0'

---

Package Exports

The package exports are defined in package.json:

{
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    },
    "./styles": "./dist/styles/index.css",
    "./styles/base": "./dist/styles/base.css",
    "./styles/themes/*": "./dist/styles/themes/*"
  }
}