Getting Started

Add SoftUI to your project in seconds. No build tools required.

Install

npm install softui-css
# or
yarn add softui-css
# or
pnpm add softui-css
# or
bun add softui-css

CDN

Drop these two lines into your <head> and you're ready to go:

<link rel="stylesheet" href="https://unpkg.com/softui-css/dist/softui.min.css">
<script src="https://unpkg.com/softui-css/dist/softui.min.js"></script>

Optional: load the default fonts (Plus Jakarta Sans and JetBrains Mono). SoftUI doesn't bundle fonts, so without these links it falls back to system fonts. See Theming → Typography for self-hosting with Fontsource.

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@300;400;500;600;700;800&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">

JavaScript

Most components are pure CSS. Some interactive components require softui.js — a dependency-free script (~117KB minified, ~28KB gzipped). Components set themselves up as soon as the DOM is ready; no setup code is needed.

Include it at the end of your <body>:

<script src="https://unpkg.com/softui-css/dist/softui.min.js"></script>

Components that need JS: Accordion, Calendar, Carousel, Chart, Collapsible, Color Picker, Combobox, Command, Context Menu, Copy Button, Countdown, Data Table, Diff, Dock (magnify effect), Drag & Drop (incl. Kanban), Drawer, Dropdown, Editable Text, File Upload, Image Lightbox, Input OTP, Menubar, Modal, Navigation Menu, Popover, Pricing (selectable), Radial Progress, Rating, Resizable, Scroll Reveal, Scrollspy, Segmented Control, Sheet, Sidebar, Slider, Speed Dial, Styled Select, Swap, Tabs, Text Rotate, Theme Toggle, Time Picker, Toast, Toggle Group, Tour, Tree View (checkbox propagation), Typewriter, and form enhancements (Password Toggle, Number Input, Tags Input).

The script initialises everything on page load and exposes window.SoftUI:

SoftUI.init(el);                     // wire up markup added after load (safe to repeat)
SoftUI.modal('#id').open();          // also .close(), .isOpen() — selector or element
SoftUI.sheet('#id').open();
SoftUI.toast({ title: 'Saved', message: 'Your changes are live.' });
SoftUI.carousel('#id').next();
SoftUI.sidebar('#id').toggle();
SoftUI.tour([{ target: '#step1', title: 'Welcome' }]);
SoftUI.theme.toggle();               // see Theming → Dark Mode Toggle
SoftUI.reveal('.my-cards');          // see Scroll Reveal
SoftUI.version;                      // '1.16.0'

If one component's markup is broken, the error is logged as [SoftUI] … failed and every other component still works. Scripted motion (carousel autoplay, typewriter, text rotate, radial count-up, scroll reveal, smooth scrolling) is turned off when the user prefers reduced motion.

Using with Frameworks

The CSS works anywhere — import the styles and use the classes. The optional JS auto-initialises on page load. In single-page apps, call SoftUI.init(el) after rendering new markup that uses JS components; calling it again is safe because elements that are already set up are skipped.

/* React — import once in your entry file, init after render */
import 'softui-css/dist/softui.min.css';
import SoftUI from 'softui-css';
import { useEffect, useRef } from 'react';

function Settings() {
  const ref = useRef(null);
  useEffect(() => { SoftUI.init(ref.current); }, []);
  return (
    <div ref={ref} className="sui-accordion">...</div>
  );
}


/* Vue — import in main.js, init in onMounted */
import 'softui-css/dist/softui.min.css';
import SoftUI from 'softui-css';

<script setup>
import { ref, onMounted } from 'vue';
const el = ref(null);
onMounted(() => SoftUI.init(el.value));
</script>
<template>
  <div ref="el" class="sui-tabs">...</div>
</template>


/* Svelte — import in +layout.svelte, init in onMount */
<script>
  import 'softui-css/dist/softui.min.css';
  import SoftUI from 'softui-css';
  import { onMount } from 'svelte';
  let node;
  onMount(() => SoftUI.init(node));
</script>
<div bind:this={node} class="sui-dropdown">...</div>


/* Astro — import in your layout */
---
import 'softui-css/dist/softui.min.css';
---
<script>import 'softui-css/dist/softui.min.js';</script>


/* Next.js — import the CSS in layout.tsx, load the JS in a client component */
// app/layout.tsx
import 'softui-css/dist/softui.min.css';

// components/SoftUIInit.tsx
'use client';
import { useEffect } from 'react';
export default function SoftUIInit() {
  useEffect(() => {
    import('softui-css').then((m) => (m.default || m).init(document));
  }, []);
  return null;
}

import SoftUI from 'softui-css' and require('softui-css') return the same object as window.SoftUI, which is also set in the browser. Importing on the server (SSR) is a no-op, so the import is safe in Next.js, Nuxt, SvelteKit and Astro. Loading the script twice (for example a CDN tag plus a bundler import) reuses the first copy. Markup that your framework renders or re-renders after load needs a SoftUI.init(el) call; pure-CSS components never do.

Events

Interactive components fire CustomEvents that bubble, so you can listen on the component or anywhere above it — including document:

document.addEventListener('sui-date-select', function (e) {
  console.log(e.target, e.detail.date);
});
EventFired ondetail
sui-date-select.sui-calendar{ date, hour, minute, period, is24h } (single), { start, end } (range)
sui-date-clear.sui-calendar—
sui-time-change.sui-timepicker{ hour, minute, period, is24h }
sui-otp-complete.sui-otp{ value }
sui-rating-change.sui-rating{ value }
sui-color-change.sui-color-picker{ color } (swatch picker)
sui-color-change.sui-color-spectrum{ hex, rgb } (spectrum picker)
sui-swap-change.sui-swap{ active } (two-state swap)
sui-swap-change.sui-swap-cycle{ state, total } (multi-state swap)
sui-editable-save.sui-editable{ value, previous }
sui-editable-cancel.sui-editable—
sui-countdown-end.sui-countdown—
sui-copy.sui-copy-btn{ text }
sui-copy-error.sui-copy-btn{ text, error }
sui-tree-toggle.sui-tree-item{ expanded }
sui-diff-change.sui-diff{ value }
sui-theme-changedocument{ theme, source }

The older names editable:save, editable:cancel and countdown:end still fire alongside the sui-* names. Native change events also bubble from styled selects, selectable pricing cards and number inputs.

Quick Start

Here's a minimal HTML page with a neumorphic button and card:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
  <link href="https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@300;400;500;600;700;800&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
  <link rel="stylesheet" href="https://unpkg.com/softui-css/dist/softui.min.css">
</head>
<body class="sui-d-flex sui-justify-center sui-align-center sui-min-vh-100">

  <div class="sui-card sui-raised sui-p-5 sui-text-center">
    <h3>Hello SoftUI</h3>
    <p class="sui-text-muted sui-mt-2 sui-mb-3">
      A neumorphic card with a soft raised shadow.
    </p>
    <button class="sui-btn sui-btn-primary">Get Started</button>
  </div>

  <script src="https://unpkg.com/softui-css/dist/softui.min.js"></script>
</body>
</html>

Using in an Existing Site

Neumorphic shadows only work when components sit on the SoftUI background (--sui-bg). SoftUI paints <body> for you, but if your site has its own background, raised and inset shadows will look muddy or disappear.

On a white background
Raised card
Inside .sui-surface
Raised card
With .sui-flat
Flat card

You have four options:

  • Whole page — let SoftUI style <body> (the default).
  • A section — wrap it in .sui-surface to paint the SoftUI background, text color, and font.
  • Individual components — add .sui-flat to drop the shadow and use a subtle border instead.
  • A whole area on your background — add .sui-flat-all to a container to replace every neumorphic shadow inside (including toggles and sliders) with a subtle outline.
<!-- A SoftUI section inside an existing page -->
<section class="sui-surface sui-p-5">
  <div class="sui-card">...</div>
</section>

<!-- A dark SoftUI section, even on a light page -->
<section class="sui-surface sui-p-5" data-theme="dark">
  <div class="sui-card">...</div>
</section>

<!-- A component on your own background -->
<button class="sui-btn sui-flat">Save</button>

<!-- Every component in an area on your own background -->
<div class="sui-flat-all">...</div>

data-theme works on any element, so you can scope light or dark mode to a single section.

Dark theme on a darker page: on a background darker than --sui-bg (for example pure black), the light half of dark-mode shadows shows as a faint halo. Wrap the area in .sui-surface with data-theme="dark" so it gets the matching background, or use .sui-flat-all.

Embed build (v1.16.0 and later). The standard stylesheet also sets page-wide base styles: a * margin/padding reset, <body> background and font, heading, paragraph, link and code styles, a thin scrollbar, and global reduced-motion and print rules. If you're adding SoftUI to a site that has its own styles, use softui-embed.min.css instead. It has the same components and tokens, but those base styles only apply inside SoftUI elements (anything with a sui- class), so the rest of your page is left alone. That includes utility classes: an element with, say, sui-mt-3 or sui-text-center counts as a SoftUI element, so it and its children get SoftUI's reset and typography.

<link rel="stylesheet" href="https://unpkg.com/softui-css/dist/softui-embed.min.css">

/* or with a bundler */
import 'softui-css/dist/softui-embed.min.css';

Components still need the SoftUI background for their shadows, so combine the embed build with .sui-surface or .sui-flat as shown above. Use one stylesheet or the other, not both.

Dark Mode

Add data-theme="dark" to your <html> element. Every component adapts automatically.

<html data-theme="dark">

To prevent a flash of light mode when the page loads, add this blocking script in your <head> before any stylesheets:

<head>
  <script>
    try {
      var t = localStorage.getItem('sui-theme');
      if (t !== 'light' && t !== 'dark')
        t = matchMedia('(prefers-color-scheme:dark)').matches ? 'dark' : 'light';
      document.documentElement.setAttribute('data-theme', t);
    } catch (e) {}
  </script>
  <link rel="stylesheet" href="softui.min.css">
</head>

The script reads the saved theme preference and sets data-theme before the first paint, so the page never flashes the wrong theme. It works with both softui.min.css and softui-embed.min.css.

For the toggle itself, add data-sui-theme-toggle to a button. softui.js handles switching, saving the choice, following the system preference and syncing tabs:

<button class="sui-theme-toggle" data-sui-theme-toggle aria-label="Dark mode">
  <svg class="sui-theme-toggle-sun" viewBox="0 0 24 24" aria-hidden="true">...</svg>
  <svg class="sui-theme-toggle-moon" viewBox="0 0 24 24" aria-hidden="true">...</svg>
</button>

See Dark Mode Toggle for light / dark / system buttons, the SoftUI.theme API and the sui-theme-change event.

Customization

SoftUI is built on CSS custom properties. Override them anywhere to match your brand:

:root {
  --sui-primary: #7C5CFC;
  --sui-radius: 12px;
  --sui-shadow-raised: 6px 6px 12px rgba(0,0,0,0.15),
                       -6px -6px 12px rgba(255,255,255,0.05);
}

See the Theming Guide for the full list of variables — colors, shadows, radius, fonts, transitions, and dark mode.

Browser Support

SoftUI works in all modern browsers. No polyfills needed. Tints, glows and focus rings use color-mix(), so they need Chrome/Edge 111+, Safari 16.2+ or Firefox 113+; older browsers lose those effects but layout and components still work.

Fully Supported:
  Chrome 111+         ✓
  Edge 111+           ✓
  Firefox 113+        ✓
  Safari 16.2+        ✓
  Opera 97+           ✓
  iOS Safari 16.2+    ✓ (momentum scrolling included)
  Android Chrome 111+ ✓

Partial Support:
  Chrome/Edge 90-110, Firefox 100-112, Safari 15-16.1
                      color-mix() tints, glows and focus rings unavailable;
                      layout and components still work
  Firefox < 121       :has() selector not available (minor styling only)
  Safari < 15.4       backdrop-filter may need -webkit- prefix (already included)

Not Supported:
  Internet Explorer   ✗ (uses CSS custom properties, flexbox gap, etc.)

SoftUI uses modern CSS features: custom properties, flexbox gap, :focus-visible, color-mix(), conic-gradient, and prefers-reduced-motion. All vendor prefixes are included where needed.

RTL (Right-to-Left)

SoftUI supports right-to-left languages like Arabic, Hebrew, and Farsi. Just add dir="rtl" to your <html> element.

<html lang="ar" dir="rtl">

Utility classes (sui-ml-*, sui-mr-*, sui-text-left/right, sui-offset-*) use CSS logical properties and adapt automatically. Components like sheets, carousels, sidebars, breadcrumbs, dropdowns, and tooltips include [dir="rtl"] overrides to flip their positioning.

See the full RTL demo →

م
مرحبا بالعالم
هذا مثال على دعم RTL

Print Styles

SoftUI includes built-in @media print styles. When users print your page or save as PDF, navbars, sidebars, modals, toasts, and other overlays are automatically hidden. Box-shadows are removed, cards and tables get clean borders, and page breaks are prevented inside components. No extra setup needed.

Explore Components View Changelog

Delete this item?

This action cannot be undone. This will permanently delete the item and remove all associated data.