✨ Overview

@usespaceui/squircle brings iOS-style squircles (mathematically perfect superellipses) to your Tailwind CSS projects. It mimics the continuous curvature corners found in Figma and Apple devices. By combining native CSS corner-shape: squircle with progressive CSS Houdini Paint Worklet fallbacks, it provides instantaneous zero-lag rendering and seamlessly integrates with Tailwind CSS.

📦 Installation

pnpm add @usespaceui/squircle
# or
npm install @usespaceui/squircle
# or
yarn add @usespaceui/squircle

Zero dependencies. Add the plugin to your Tailwind configuration (v3) or your CSS entry file (v4).

🚀 Setup

Because the plugin relies on a CSS Houdini worklet to draw the shape, you must initialize the script once in your app.

With React / Next.js

Since the worklet interacts with the browser DOM, initialize it inside a Client Component provider.

// components/SquircleProvider.tsx
'use client'
import * as React from 'react'
import { initSquircle } from '@usespaceui/squircle'

// Initialize immediately as client bundle loads before paint
if (typeof window !== 'undefined') {
  initSquircle()
}

export function SquircleProvider({ children }: { children: React.ReactNode }) {
  return <>{children}</>
}

Wrap your root layout:

import { SquircleProvider } from './SquircleProvider'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <SquircleProvider>{children}</SquircleProvider>
      </body>
    </html>
  )
}

With Vanilla JS

Initialize the worklet directly in your client-side entry file:

import { initSquircle } from '@usespaceui/squircle'

if (typeof window !== 'undefined') {
  initSquircle()
}

Configure Tailwind CSS 4

In Tailwind CSS v4, add the plugin directly to your CSS entry point (e.g. globals.css or styles.css):

@import 'tailwindcss';
@plugin "@usespaceui/squircle";

Configure Tailwind CSS 3

Add the squircle plugin to your tailwind.config.js or tailwind.config.ts:

CommonJS (tailwind.config.js)

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {},
  },
  plugins: [require('@usespaceui/squircle')],
}

ESM / TypeScript (tailwind.config.ts or tailwind.config.mjs)

import type { Config } from 'tailwindcss'
import squircle from '@usespaceui/squircle'

const config: Config = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {},
  },
  plugins: [squircle],
}

export default config

🎨 Usage

1. Sizing

Apply the squircle utility alongside your Tailwind rounded-* classes:

<!-- Standard Tailwind sizes -->
<button class="squircle rounded-2xl bg-black text-white px-6 py-3">
  Space UI Squircle
</button>

<!-- Smooth hover transitions between radii -->
<button class="squircle rounded-7xl hover:rounded-3xl transition-all duration-300">
  Interactive Squircle
</button>

<!-- Pill / Circle -->
<div class="squircle rounded-full">...</div>

<!-- Arbitrary values -->
<div class="squircle rounded-[40px]">...</div>

2. Smoothing Intensity

By default, squircle applies a 60% smooth transition, perfectly matching Apple (iOS) and Figma's native continuous curvature.

You can adjust this intensity using modifiers (/0, /20, /40, /60, /80, /100):

<!-- Maximum smoothing (pronounced superellipse) -->
<button class="squircle/100 rounded-3xl">...</button>

<!-- Minimal smoothing (closer to a plain rounded rectangle) -->
<button class="squircle/20 rounded-3xl">...</button>

<!-- Default is 60% (matches Apple iOS & Figma perfectly) -->
<button class="squircle rounded-3xl">...</button>

Note on custom smoothing: Custom smoothing modifiers are processed dynamically by the CSS Houdini engine. In browsers with native corner-shape: squircle, the native CSS superellipse curve is used by default.

3. Borders & Outlines

Use standard Tailwind border utilities (border, border-2, border-8, etc.). The squircle contour shapes both the background and the border:

<!-- 8px border following squircle curvature -->
<button class="squircle rounded-7xl border-8 border-red-500 bg-black text-white">
  Bordered Squircle
</button>

<!-- 1px subtle border -->
<div class="squircle rounded-3xl border border-border bg-card">
  Card with Squircle Border
</div>

🧰 Utilities Included

• initSquircle() Registers the CSS Houdini Paint Worklet and sets up the custom CSS properties (--tw-squircle-w and --tw-squircle-smooth). It is safe to call multiple times and fails gracefully in environments where Houdini is not supported.

• plugin(tailwindcss) The default export is a Tailwind CSS plugin that provides the squircle utility class. It automatically provides fallback border-radius styles for browsers that don't support the Paint API.

Features

• 💃 Native Tailwind Integration: Use the squircle utility alongside standard rounded-* classes. No framework-specific wrappers required, and if the browser doesn't support the Paint API, standard rounded fallback values apply automatically.
• ⚡ Zero-JS Layout Thrashing: Driven by the native CSS Paint API (Houdini). No ResizeObserver, no DOM manipulation, no SVG paths. Repaints happen instantly on the compositor thread.
• 👌 Framework Agnostic: Works in React, Vue, Svelte, Solid, or plain HTML.

📦 Related Packages

| Package | Description | | -------------------------------------------------------------- | --------------------------------------- | | @usespaceui/avatars | Generative deterministic avatars | | @usespaceui/sounds | UI sound effects and audio interactions |

🪪 License

MIT — Free for commercial and personal use.

📚 Resources

• 🔍 Explore the squircles & Playground
• 🌍 Space UI Official Site

🛠 Maintenance

If you find a bug or have a feature request, please open an issue on GitHub. Engine internals are intentionally not part of the public API.