@gxp-dev/uikit

Vue 3 UI component library for GXP platform applications, built on shadcn-vue, reka-ui, and Tailwind CSS.

📖 Browse the live Storybook → — every component, composable, and experience-flow page with interactive props, slot examples, and usage notes.

Installation

pnpm add @gxp-dev/uikit

Setup

1. Import Styles

Import the library styles in your application entry point:

// main.ts
import '@gxp-dev/uikit/styles'

This includes the default GXP theme. For custom theming, see the Theming section.

2. Configure Tailwind (Optional)

If you want to extend the library styles with Tailwind in your application:

// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{vue,ts}',
    './node_modules/@gxp-dev/uikit/**/*.js'
  ]
}

Usage

<script setup lang="ts">
import { Button, Input, Dialog, DialogContent, DialogTrigger } from '@gxp-dev/uikit'
</script>

<template>
  <div>
    <Input v-model="text" placeholder="Enter text" />
    <Button variant="default">Submit</Button>

    <Dialog>
      <DialogTrigger>Open Dialog</DialogTrigger>
      <DialogContent>
        <p>Dialog content</p>
      </DialogContent>
    </Dialog>
  </div>
</template>

Components

The library includes 40+ shadcn-vue UI primitives, 8 domain-specific components, 5 composables, and utility functions.

UI Primitives (shadcn-vue)

Built on reka-ui with full accessibility support:

Form Controls: Button, Input, Textarea, Label, Checkbox, Switch, RadioGroup, Select, Slider, Form

Layout: Card, Separator, AspectRatio, ScrollArea, Sheet, Tabs, Accordion, Collapsible

Overlays: Dialog, AlertDialog, Popover, Tooltip, HoverCard, ContextMenu, DropdownMenu, Command

Feedback: Alert, Badge, Avatar, Skeleton, Progress, Toaster (Sonner)

Navigation: Pagination, Table, Menubar, NavigationMenu, Calendar

Domain Components

Purpose-built components for GXP platform applications:

• Spinner: Loading spinner with customizable size and color
• Header: Application header with logo, title, and navigation
• Countdown: Animated countdown timer with customizable display
• VideoPlayer: Video playback with custom controls and events
• FileUploader: Drag-and-drop file upload with preview and validation
• BarcodeScanner: Real-time barcode scanning using device camera
• Leaderboard: Animated leaderboard with activity notifications and award icons
• AudioVisualizer: Real-time audio visualization with canvas rendering

Composables

Reusable Vue 3 composition functions:

• useMedia: Media device access (camera, microphone) with recording capabilities
• useScanning: Barcode/QR code scanning functionality
• useAnimations: Animation utilities for transitions and effects
• useErrors: Centralized error handling and display
• useNfcListener: NFC tag reading and simulation

Experience Flow

A state-machine-driven orchestrator with 20 prebuilt page components for multi-stage interactive apps (kiosks, photo booths, AI experiences):

• useExperience(config) — navigation, reactive context, skip conditions, action binding, busy/error state
• <ExperienceFlow :flow /> — renderer with transitions and loading/error slots
• useExperienceApi({ callApi }) — optional adapter that turns callApi into typed named operations (publishPost, createPrintJob, processImage, …)
• 20 prebuilt pages — Welcome, Terms, Instructions, Camera + Review, Video + Review, Audio + Review, Drawing, Notepad, Text, Prompt, Options, Form, ResultsGallery, PhotoEdit, Share, Loading, Final

<script setup lang="ts">
import { callApi } from '@gxp-dev/devtools'
import {
  useExperience, useExperienceApi, ExperienceFlow,
  WelcomePage, TermsPage, CameraPage, CameraReviewPage, FinalPage,
} from '@gxp-dev/uikit'

const api = useExperienceApi({ callApi })

const flow = useExperience({
  api,
  pages: [
    { name: 'welcome', component: WelcomePage },
    { name: 'terms',   component: TermsPage,   props: { html: tos } },
    { name: 'capture', component: CameraPage },          // → ctx.photoBlob
    { name: 'review',  component: CameraReviewPage },    // default action: publishPost → ctx.post
    { name: 'final',   component: FinalPage },
  ],
})
</script>

<template>
  <ExperienceFlow :flow="flow" />
</template>

See Experience Flow → Overview for the full guide, Pages reference, and API adapter.

Theming

The library uses CSS variables for theming, compatible with the GXP platform theming system.

Using the Default Theme

The default import includes the GXP theme:

import '@gxp-dev/uikit/styles'

Custom Theming

For custom themes, import only the base styles and define your own CSS variables:

// Import base styles without theme
import '@gxp-dev/uikit/styles/base'

Then define the CSS variables in your application:

:root {
  /* Core Platform Variables */
  --page_background_color: #ffffff;
  --page_text_color: #222222;
  --input_field_background_color: #f5f5f5;
  --input_field_text_color: #222222;
  --input_field_border_color: #cccccc;

  /* Primary Button */
  --primary_button_background_color: #0066cc;
  --primary_button_text_color: #ffffff;
  --primary_button_border_color: #0066cc;

  /* Secondary Button */
  --secondary_button_background_color: #f5f5f5;
  --secondary_button_text_color: #222222;
  --secondary_button_border_color: #cccccc;

  /* Shadcn/Tailwind mappings (auto-derived from above) */
  --background: var(--page_background_color);
  --foreground: var(--page_text_color);
  --primary: var(--primary_button_background_color);
  --primary-foreground: var(--primary_button_text_color);
  --secondary: var(--secondary_button_background_color);
  --secondary-foreground: var(--secondary_button_text_color);
  --border: var(--input_field_border_color);
  --input: var(--input_field_background_color);
  --ring: var(--primary_button_border_color);
  --radius: 0.5rem;
}

Utilities

cn(): Merge Tailwind CSS classes with conflict resolution

processUploadedImage(): Process and validate uploaded image files

convertToCanvasBlob(): Convert canvas to blob for image manipulation

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

// Class merging
const classes = cn('base-class', condition && 'conditional-class')

// Image processing
const blob = await processUploadedImage(file, { maxWidth: 1920 })

Development

# Install dependencies
pnpm install

# Start dev server
pnpm dev

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Build library
pnpm build

# Start Storybook locally
pnpm storybook

# Build the static Storybook bundle (deployed to GitHub Pages by CI)
pnpm storybook:build

Exports

// UI Primitives
import {
  Button,
  Input,
  Label,
  Textarea,
  Separator,
  Badge,
  Avatar,
  AvatarImage,
  AvatarFallback,
  Skeleton,
  Alert,
  AlertTitle,
  AlertDescription,
  Card,
  CardHeader,
  CardTitle,
  CardDescription,
  CardContent,
  CardFooter,
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
  DialogFooter,
  AlertDialog,
  Checkbox,
  Select,
  SelectTrigger,
  SelectContent,
  SelectItem,
  Tabs,
  TabsList,
  TabsTrigger,
  TabsContent,
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuItem,
  Toaster,
  Progress,
  AspectRatio,
  ScrollArea,
  Accordion,
  AccordionItem,
  AccordionTrigger,
  AccordionContent,
  Collapsible,
  Popover,
  Tooltip,
  TooltipProvider,
  Switch,
  Slider,
  Sheet,
  RadioGroup,
  HoverCard,
  Pagination,
  Table,
  ContextMenu,
  Form,
  Command,
  Calendar,
  Menubar,
  NavigationMenu,
} from '@gxp-dev/uikit'

// Domain Components
import {
  Spinner,
  Header,
  Countdown,
  VideoPlayer,
  FileUploader,
  BarcodeScanner,
  Leaderboard,
  ActivityNotifications,
  AwardIcon,
  AudioVisualizer,
} from '@gxp-dev/uikit'

// Composables
import {
  useMedia,
  useScanning,
  useAnimations,
  useErrors,
  useNfcListener,
  simulateNfcScan,
} from '@gxp-dev/uikit'

// Experience Flow
import {
  useExperience,
  useExperienceApi,
  withExperienceDefaults,
  ExperienceFlow,
  WelcomePage,
  TermsPage,
  InstructionsPage,
  CameraPage,
  CameraReviewPage,
  VideoCapturePage,
  VideoReviewPage,
  AudioCapturePage,
  AudioReviewPage,
  DrawingPage,
  NotepadPage,
  TextPage,
  PromptPage,
  OptionsPage,
  FormPage,
  ResultsGalleryPage,
  PhotoEditPage,
  SharePage,
  LoadingPage,
  FinalPage,
} from '@gxp-dev/uikit'

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

// Types
import type {
  ButtonVariants,
  SpinnerProps,
  HeaderProps,
  CountdownProps,
  VideoPlayerProps,
  FileUploaderProps,
  BarcodeScannerProps,
  LeaderboardProps,
  LeaderboardEntry,
  AudioVisualizerProps,
  UseMediaReturn,
  UseScanningReturn,
  UseAnimationsReturn,
  UseErrorsReturn,
  UseNfcListenerReturn,
  // Experience Flow
  ExperienceApi,
  ExperienceAction,
  ExperienceActionFn,
  ExperienceActionName,
  ExperienceContext,
  ExperienceFlowConfig,
  ExperienceFlowProps,
  ExperiencePageDef,
  ExperiencePageDefaults,
  UseExperienceReturn,
  UseExperienceApiOptions,
  CallApi,
  PublishPostInput,
  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'

Requirements

• Vue 3.4+
• Node.js 18+

License

MIT