Add SoftUI to your project in seconds. No build tools required.
npm install softui-css
# or
yarn add softui-css
# or
pnpm add softui-css
# or
bun add softui-css
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">
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.
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.
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);
});
| Event | Fired on | detail |
|---|---|---|
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-change | document | { 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.
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>
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.
.sui-surface
.sui-flat
You have four options:
<body> (the default)..sui-surface to paint the SoftUI background, text color, and font..sui-flat to drop the shadow and use a subtle border instead..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.
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.
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.
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.
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.
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.
This is a neumorphic modal dialog. It features backdrop blur, smooth animations, and focus trap. Press Escape or click outside to close.
Your session will expire in 5 minutes. Would you like to stay signed in?
This action cannot be undone. This will permanently delete the item and remove all associated data.
This modal takes up the entire viewport. Useful for immersive content, editors, or media viewers.
Press Escape or click the close button to dismiss.
By accessing and using this service, you accept and agree to be bound by the terms and provision of this agreement. In addition, when using these particular services, you shall be subject to any posted guidelines or rules applicable to such services. Any participation in this service will constitute acceptance of this agreement.
Permission is granted to temporarily download one copy of the materials on this website for personal, non-commercial transitory viewing only. This is the grant of a license, not a transfer of title, and under this license you may not modify or copy the materials, use the materials for any commercial purpose, attempt to reverse engineer any software, or remove any copyright notations.
The materials on this website are provided on an 'as is' basis. We make no warranties, expressed or implied, and hereby disclaim and negate all other warranties including, without limitation, implied warranties or conditions of merchantability, fitness for a particular purpose, or non-infringement of intellectual property.
In no event shall this company or its suppliers be liable for any damages (including, without limitation, damages for loss of data or profit, or due to business interruption) arising out of the use or inability to use the materials, even if we have been notified orally or in writing of the possibility of such damage.
The materials appearing on this website could include technical, typographical, or photographic errors. We do not warrant that any of the materials on its website are accurate, complete or current. We may make changes to the materials contained on its website at any time without notice.
We have not reviewed all of the sites linked to this website and are not responsible for the contents of any such linked site. The inclusion of any link does not imply endorsement. Use of any such linked web site is at the user's own risk.
We may revise these terms of service for this website at any time without notice. By using this website you are agreeing to be bound by the then current version of these terms of service. Any changes will be posted on this page with an updated revision date.
These terms and conditions are governed by and construed in accordance with applicable laws and you irrevocably submit to the exclusive jurisdiction of the courts in that location. If any provision of these terms shall be unlawful, void, or unenforceable, then that provision shall be deemed severable and shall not affect the validity of the remaining provisions.
Clicking outside this modal won't close it. Instead, the modal will shake to indicate it requires explicit action. Pressing Escape shakes it too — use the close button or an action to dismiss.
This modal has no backdrop blur. The background is visible but dimmed.
A subtle 3px backdrop blur. Content behind is slightly softened.
A heavy 12px backdrop blur. Background is barely recognizable.
Maximum 20px blur. Background is fully frosted.
This is a default right-side sheet. It slides in from the right edge of the screen with a blurred backdrop.
Sheets are great for navigation menus, settings panels, detail views, and forms that don't need to interrupt the main content flow.
This sheet slides down from the top. Great for announcements, notification panels, or search interfaces.
This is a small (280px) right-side sheet.
This is a large (480px) right-side sheet. Great for forms, detail views, or complex content.
Clicking outside this sheet won't close it. The sheet will shake to indicate it requires explicit action. Pressing Escape shakes it too. Use the close button to dismiss.