appy-ui

A React component library with iOS Liquid Glass and Material 3 design system support. Built with Tailwind CSS 4, supporting automatic platform detection and adaptive styling.

Installation

npm install appy-ui

Peer Dependencies

Make sure you have these peer dependencies installed:

npm install react react-dom tailwindcss

Setup

1. CSS Configuration

Add the following imports to your project's main CSS file (e.g., globals.css):

@import "tailwindcss";
@import "appy-ui/styles.css";
@source "../node_modules/appy-ui/dist/**/*.js";

2. Provider Setup

Wrap your app with the DesignSystemProvider:

import { DesignSystemProvider } from 'appy-ui';

function App() {
  return (
    <DesignSystemProvider>
      <YourApp />
    </DesignSystemProvider>
  );
}

Usage

import { Button, Card, CardContent, CardHeader, CardTitle } from 'appy-ui';

function MyComponent() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Welcome</CardTitle>
      </CardHeader>
      <CardContent>
        <Button>Click me</Button>
      </CardContent>
    </Card>
  );
}

Design System

The library automatically detects the user's platform and applies the appropriate design system:

• iOS devices: iOS Liquid Glass styling (.ios class)
• Android devices: Material 3 styling (.material class)
• Desktop: Default styling

You can also manually set the design system:

import { useDesignSystem } from 'appy-ui';

function Settings() {
  const { designSystem, setDesignSystem, isAuto } = useDesignSystem();

  return (
    <div>
      <p>Current: {designSystem}</p>
      <button onClick={() => setDesignSystem('auto')}>Auto</button>
      <button onClick={() => setDesignSystem('ios')}>iOS</button>
      <button onClick={() => setDesignSystem('material')}>Material</button>
    </div>
  );
}

Platform-Specific Styling

Use Tailwind CSS custom variants for platform-specific styles:

<div className="bg-white ios:bg-glass-bg material:bg-m3-surface">
  Content
</div>

Layout Components

TabBar

Adaptive navigation that changes based on platform/form factor:

import { TabBar, type TabItem } from 'appy-ui';
import { Link, useRouterState } from '@tanstack/react-router';

const items: TabItem[] = [
  { id: 'home', label: 'Home', path: '/', icon: HomeIcon, activeIcon: HomeFilledIcon },
  { id: 'profile', label: 'Profile', path: '/profile', icon: UserIcon, activeIcon: UserFilledIcon },
];

function Navigation() {
  const { location } = useRouterState();

  return (
    <TabBar
      items={items}
      currentPath={location.pathname}
      LinkComponent={Link}
    />
  );
}

Header

Adaptive header with scroll animation support:

import { Header, SecondaryPageHeader, TabPageHeader } from 'appy-ui';

// For secondary pages (with back button)
<SecondaryPageHeader title="Settings" onBack={() => navigate(-1)} />

// For tab pages (with animated title)
<TabPageHeader title="Home" />

// Custom composition
<Header.Root>
  <Header.BackButton onClick={handleBack} />
  <Header.AnimatedTitle>My Page</Header.AnimatedTitle>
  <Header.TrailingAction>
    <button>Action</button>
  </Header.TrailingAction>
</Header.Root>

Components

UI Components (55+)

• Accordion
• Alert, AlertDialog
• AspectRatio
• Avatar (with Badge, Group)
• Badge
• Breadcrumb
• Button, ButtonGroup
• Calendar
• Card
• Carousel
• Chart
• Checkbox
• Collapsible
• Combobox
• Command
• ContextMenu
• Dialog
• Drawer
• DropdownMenu
• Empty
• Field (form)
• HoverCard
• Input, InputGroup, InputOTP
• Item
• Kbd
• Label
• Menubar
• NativeSelect
• NavigationMenu
• Pagination
• Popover
• Progress, ProgressiveBlur
• RadioGroup
• Resizable
• ScrollArea
• Select
• Separator
• Sheet
• Sidebar
• Skeleton
• Slider
• Sonner (Toast)
• Spinner
• Switch
• Table
• Tabs
• Textarea
• Toggle, ToggleGroup
• Tooltip

Layout Components

• TabBar (iOS, Android, Web variants)
• Header (with animated title)
• WebNavBar
• WebFooter

Hooks

• useDesignSystem() - Access design system context
• useDeviceContext() - Platform, form factor, keyboard detection
• useScrolled() - Track scroll position
• useIsMobile() - Mobile breakpoint detection

License

MIT