Getting Started

Requires React 18.2+ or 19 and a bundler that supports CSS imports. Keep react and react-dom on the same version; TypeScript projects should use their matching @types major versions.

pnpm add @swiftuijs/ui react react-dom

Import shared styles once at your application root. Component styles are included by their JavaScript entries.

import '@swiftuijs/ui/style/index.css';

Use normal React state and HTML props:

'use client';

import { useState } from 'react';
import { Button, Text, VStack } from '@swiftuijs/ui';

export function Counter() {
  const [count, setCount] = useState(0);
  return (
    <VStack spacing={12} alignment="leading">
      <Text>{count} clicks</Text>
      <Button onClick={() => setCount(value => value + 1)}>Add one</Button>
    </VStack>
  );
}

For the smallest CSS footprint, import individual components:

import { Button } from '@swiftuijs/ui/components/Button';

Next.js and SSR

Import shared styles in app/layout.tsx. Published component entries declare their client boundary, so server components can import them. Put state and event handlers in your own 'use client' component. Viewport hooks initially return null; handle that state without reading window during rendering. Modal content uses portals and appears after mounting.

Use with Twill

You can also write SwiftUI.js views in Twill, our sibling Swift-inspired language for JavaScript and TypeScript. Follow Twill's React integration guide to configure .twillx compilation. Component imports, React state, props and the shared-style import above stay the same.

Make it yours

Pass className, style, HTML attributes and aria-* props. Override CSS variables at an application root or theme boundary; Tailwind can style your application without becoming a dependency of the component library.

Try the workspace demo, read responsive behavior, and check the capability matrix before adopting experimental components.