@swiss-ui/svelte

Svelte 5 components for the Swiss UI design system.

Installation

npm install @swiss-ui/svelte svelte

Architecture

Every component ships in two modes:

• Headless (@swiss-ui/svelte) — logic, state, ARIA, no classes by default
• Styled (@swiss-ui/svelte/styled) — wraps headless with swiss-* classes from @swiss-ui/core

<!-- Headless: bring your own styles -->
<script>
  import { SwissButton } from '@swiss-ui/svelte'
</script>

<SwissButton variant="solid">Save</SwissButton>

<!-- Styled: uses Swiss UI design tokens -->
<script>
  import { StyledSwissButton } from '@swiss-ui/svelte/styled'
</script>

<StyledSwissButton variant="solid">Save</StyledSwissButton>

Svelte 5 Patterns

All components use Svelte 5 runes exclusively:

• $state() for reactive state
• $derived() for computed values
• $effect() for side effects
• $props() with typed interfaces
• $bindable() for two-way binding
• Snippets ({#snippet} / {@render}) instead of named slots
• setContext / getContext with Symbol keys for compound components

Components

Primitives

| Component | Props | Description | |-----------|-------|-------------| | SwissBox | el, class | Polymorphic box element | | SwissTextPrimitive | el, class | Polymorphic text element |

Layout

| Component | Props | Description | |-----------|-------|-------------| | SwissContainer | size (sm|md|lg|xl|full) | Constrained width container | | SwissStack | direction, gap, align, justify | Flex stack | | SwissGrid | cols, gap, align | CSS grid wrapper | | SwissGridItem | colSpan, rowSpan | Grid cell |

Typography

| Component | Props | Description | |-----------|-------|-------------| | SwissHeading | el, level (1–6), size, weight, align | Heading h1–h6 | | SwissText | el, size, weight, align, color, truncate | Text paragraph or span |

Controls

| Component | Props | Snippets | Bindable | |-----------|-------|----------|---------| | SwissButton | variant, size, loading, disabled, el, type | leftIcon, rightIcon | — | | SwissInput | size, type, disabled, invalid, id, describedBy | leftAddon, rightAddon | bind:value | | SwissTextarea | rows, resize, autoResize, disabled, invalid | — | bind:value | | SwissSelect | size, disabled, invalid, id | children (options) | bind:value | | SwissCheckbox | indeterminate, disabled, invalid, id, name, value | children (label) | bind:checked | | SwissRadio | value, disabled, invalid, id | children (label) | — | | SwissRadioGroup | name, disabled, orientation | children | bind:value | | SwissSwitch | disabled, id, name | children (label) | bind:checked |

Feedback

| Component | Props | Snippets | |-----------|-------|----------| | SwissBadge | variant (solid|outline|subtle), color | children | | SwissAlert | variant (info|success|warning|error) | icon, title, description, actions | | SwissSpinner | size, color, label | — |

Overlay

SwissModal

Compound component. Manages focus trap, Escape key, scroll lock, and ARIA.

| Part | Props | Bindable | |------|-------|---------| | SwissModal | onclose | bind:open | | SwissModalOverlay | closeOnClick | — | | SwissModalContent | — | — | | SwissModalHeader | — | — | | SwissModalBody | — | — | | SwissModalFooter | — | — | | SwissModalCloseButton | — | — |

<script>
  import {
    SwissModal,
    SwissModalOverlay,
    SwissModalContent,
    SwissModalHeader,
    SwissModalBody,
    SwissModalFooter,
    SwissModalCloseButton,
  } from '@swiss-ui/svelte'

  let open = $state(false)
</script>

<button onclick={() => open = true}>Open</button>

<SwissModal bind:open>
  <SwissModalOverlay />
  <SwissModalContent>
    <SwissModalHeader>
      Title
      <SwissModalCloseButton />
    </SwissModalHeader>
    <SwissModalBody>Content goes here</SwissModalBody>
    <SwissModalFooter>
      <SwissButton onclick={() => open = false}>Close</SwissButton>
    </SwissModalFooter>
  </SwissModalContent>
</SwissModal>

SwissTooltip

| Props | Snippets | Bindable | |-------|----------|---------| | placement, delay, disabled | children (trigger), content | bind:open |

<script>
  import { SwissTooltip } from '@swiss-ui/svelte'
</script>

<SwissTooltip placement="top">
  <button>Hover me</button>
  {#snippet content()}
    Tooltip text
  {/snippet}
</SwissTooltip>

SwissDropdown

Compound component with full keyboard navigation (Arrow, Enter, Escape, Home, End).

| Part | Props | Bindable | |------|-------|---------| | SwissDropdown | — | bind:open | | SwissDropdownTrigger | — | — | | SwissDropdownContent | placement | — | | SwissDropdownItem | disabled, onselect | — | | SwissDropdownSeparator | — | — | | SwissDropdownLabel | — | — |

<script>
  import {
    SwissDropdown,
    SwissDropdownTrigger,
    SwissDropdownContent,
    SwissDropdownItem,
    SwissDropdownSeparator,
    SwissDropdownLabel,
  } from '@swiss-ui/svelte'
</script>

<SwissDropdown>
  <SwissDropdownTrigger>Menu</SwissDropdownTrigger>
  <SwissDropdownContent>
    <SwissDropdownLabel>Actions</SwissDropdownLabel>
    <SwissDropdownItem onselect={() => console.log('edit')}>Edit</SwissDropdownItem>
    <SwissDropdownItem onselect={() => console.log('copy')}>Copy</SwissDropdownItem>
    <SwissDropdownSeparator />
    <SwissDropdownItem disabled>Delete</SwissDropdownItem>
  </SwissDropdownContent>
</SwissDropdown>

Actions

Import from @swiss-ui/svelte/actions:

| Action | Parameters | Description | |--------|------------|-------------| | use:portal | target?: string \| HTMLElement | Renders element into a different DOM node | | use:focusTrap | active: boolean | Traps keyboard focus within element | | use:clickOutside | handler: () => void | Fires handler on click outside element | | use:escapeKey | handler: () => void | Fires handler on Escape keydown | | use:autoPlacement | { trigger, placement, offset } | Positions element relative to trigger |

<script>
  import { portal, focusTrap, clickOutside, escapeKey } from '@swiss-ui/svelte/actions'

  let open = $state(false)
</script>

{#if open}
  <div
    use:portal={'body'}
    use:focusTrap={open}
    use:clickOutside={() => open = false}
    use:escapeKey={() => open = false}
  >
    Popup content
  </div>
{/if}

RadioGroup Example

<script>
  import { SwissRadioGroup, SwissRadio } from '@swiss-ui/svelte'

  let selected = $state('a')
</script>

<SwissRadioGroup bind:value={selected} orientation="horizontal">
  <SwissRadio value="a">Option A</SwissRadio>
  <SwissRadio value="b">Option B</SwissRadio>
  <SwissRadio value="c" disabled>Option C</SwissRadio>
</SwissRadioGroup>

Headless vs Styled

<!-- Headless: data attributes for styling -->
<SwissButton variant="solid" size="md" data-variant="solid">
  Click
</SwissButton>

<!-- Styled: adds swiss-button class -->
<StyledSwissButton variant="solid">
  Click
</StyledSwissButton>

Accessibility

All components follow WCAG 2.1 AA:

• Semantic HTML elements and ARIA roles
• aria-invalid, aria-describedby on form fields
• aria-modal, aria-labelledby, aria-describedby on dialogs
• aria-checked="mixed" on indeterminate checkboxes
• role="switch" with aria-checked on SwissSwitch
• role="radiogroup" with aria-orientation on SwissRadioGroup
• Full keyboard navigation on Dropdown (Arrow, Enter, Escape, Home, End)
• Focus trap on Modal with first-element focus on open
• Focus returns to trigger on Modal/Dropdown close

SvelteKit SSR

All components are SSR-safe:

• Svelte actions run only in the browser (mount-time)
• $effect() blocks that access document run only client-side
• Portal renders nothing during SSR
• document.body.style modifications are guarded by $effect()

Build

npm run build      # svelte-package → dist/
npm run dev        # watch mode
npm run check      # svelte-check
npm test           # vitest run

Individual Component Imports

import { SwissButton } from '@swiss-ui/svelte/SwissButton'
import { SwissModal } from '@swiss-ui/svelte/SwissModal'
import { SwissDropdown } from '@swiss-ui/svelte/SwissDropdown'