@swiss-ui/react

Headless React components for Swiss UI design system.

Installation

npm install @swiss-ui/react

yarn add @swiss-ui/react

pnpm add @swiss-ui/react

Usage

Headless import

All components are exported from the root entry with no default styles attached. You provide all styling yourself.

import { Button, Input, Modal } from '@swiss-ui/react'

You can also import individual components from their own sub-paths to enable more granular code splitting:

import { Button } from '@swiss-ui/react/button'
import { Input } from '@swiss-ui/react/input'

Styled import

The @swiss-ui/react/styled entry re-exports every component with a swiss-* CSS class pre-applied. Apply the swiss-ui CSS token sheet and component stylesheet alongside this entry to get themed components out of the box.

import { Button, Input, Stack } from '@swiss-ui/react/styled'

Components

| Component | Description | Key props | |---|---|---| | Box | Generic polymorphic container | as | | Text | Inline or block text | as, size, weight, align, truncate | | Container | Centered max-width wrapper | size (sm / md / lg / xl / full) | | Stack | Vertical flex container | gap, align, justify | | Grid | CSS grid container | cols, gap, align | | GridItem | Grid child with span support | colSpan, rowSpan | | Heading | Semantic heading h1-h6 | level, size, weight, align, as | | Button | Polymorphic action trigger | variant, size, loading, leftIcon, rightIcon, as | | Input | Text input with addons | size, invalid, leftAddon, rightAddon, describedBy | | Textarea | Multi-line text input | size, invalid, resize, autoResize, describedBy | | Select | Native select element | size, invalid, placeholder, describedBy | | Checkbox | Checkbox with indeterminate state | indeterminate, invalid | | Radio | Radio button | invalid | | RadioGroup | Radio group context provider | name, value, onChange, orientation | | Switch | Toggle switch | checked, defaultChecked, onChange | | Badge | Inline status indicator | variant, color | | Alert | Contextual message block | variant, icon, title, description, actions | | Spinner | Loading indicator | size, color, label | | Modal | Accessible dialog | isOpen, onClose | | ModalOverlay | Modal backdrop | | | ModalContent | Dialog container with focus trap | | | ModalHeader | Header slot | | | ModalBody | Body slot, provides aria-describedby | | | ModalFooter | Footer slot | | | ModalCloseButton | Pre-wired close button | | | Tooltip | Hover/focus tooltip | content, placement, delay, disabled | | Dropdown | Menu dropdown container | | | DropdownTrigger | Menu trigger button | | | DropdownContent | Menu panel | | | DropdownItem | Menu action item | disabled | | DropdownSeparator | Visual separator | | | DropdownLabel | Non-interactive group label | |

Accessibility

The following accessibility features are implemented out of the box:

• All interactive elements use native HTML elements or appropriate ARIA roles.
• Button supports polymorphic rendering; when rendered as a non-button element, aria-disabled is set instead of the disabled attribute.
• Input, Textarea, and Select expose aria-invalid and aria-describedby props.
• Checkbox supports the indeterminate state via the DOM property.
• RadioGroup renders a radiogroup role; Radio buttons share a name from context.
• Switch uses role="switch" with aria-checked.
• Alert maps info and success variants to role="status" and warning / error to role="alert".
• Spinner exposes role="status" with a configurable aria-label.
• Modal locks body scroll, traps focus inside ModalContent, and closes on Escape.
• Tooltip renders role="tooltip" inside a portal and links to the trigger via aria-describedby.
• Dropdown follows the ARIA menu button pattern: aria-haspopup, aria-expanded, aria-controls, and full keyboard navigation (ArrowUp / ArrowDown / Home / End / Escape / Tab).

Customization

Components use CSS custom properties for all design tokens. Override them on :root or any ancestor element:

:root {
  --swiss-font-size-md: 1rem;
  --swiss-spacing-4: 1rem;
  --swiss-color-primary: #0055cc;
}

The data-variant, data-size, data-color, and data-component attributes on every element give you CSS attribute selectors without any class naming convention:

[data-component="button"][data-variant="solid"] {
  background: var(--swiss-color-primary);
}

SSR compatibility

All portal-based components (Modal, Tooltip, Dropdown) guard against document access with typeof document !== 'undefined' checks, making them safe to render in server environments. They hydrate correctly on the client without any additional configuration.