Squircle

@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 utilizing the CSS Houdini Paint Worklet API, it provides native-like performance and seamlessly integrates with Tailwind CSS.

Features

• 💃 Native Tailwind Integration: Use utility classes like squircle-2xl just like you would rounded-2xl. No framework-specific wrappers required.
• ⚡️ Zero-JS Layout Thrashing: Driven by the native CSS Paint API (Houdini). Repaints happen instantly on the compositor thread.
• ✨ Native Borders: The worklet automatically detects and renders standard Tailwind borders perfectly onto the squircle shape.
• 🛠️ Customizable Smoothing: Adjust the smoothing intensity with modifiers (/0 to /100).

Installation

If you initialized Space UI in your project, the squircle plugin is already included! If not, you can install it manually:

pnpm add @usespaceui/squircle

Setup

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

1. Provider Initialization (React / Next.js)

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

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

export function SquircleProvider({ children }: { children: React.ReactNode }) {
  React.useEffect(() => {
    initSquircle()
  }, [])

  return <>{children}</>
}

Wrap your root layout with this provider:

import { SquircleProvider } from '@/components/providers/squircle-provider'

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

2. Tailwind CSS Configuration

For Tailwind CSS v4: Add the squircle plugin to your app.css or globals.css.

@plugin '@usespaceui/squircle';

For Tailwind CSS v3: Add the squircle plugin to your tailwind.config.ts.

import squirclePlugin from '@usespaceui/squircle'

export default {
  plugins: [squirclePlugin],
}

Usage

You do NOT need a React component to use Squircles. Just use the squircle-* classes on standard HTML elements! The classes automatically map to your Tailwind theme's borderRadius values.

1. Sizing

export default function SpaceUI() {
  return (
    <>
      {/* Matches rounded-md */}
      <div className="squircle rounded-md p-4 bg-primary text-primary-foreground">Squircle!</div>

      {/* Matches rounded-2xl */}
      <div className="squircle rounded-2xl bg-muted" />

      {/* Perfectly circular/pill shape */}
      <div className="squircle rounded-full" />

      {/* Arbitrary values are fully supported */}
      <div className="squircle rounded-[40px]" />
    </>
  )
}

2. Smoothing Intensity

By default, the plugin applies a 60% smooth transition between the straight edge and the corner arc, perfectly matching native OS smoothing.

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

export default function SpaceUI() {
  return (
    <>
      {/* Maximum smoothing */}
      <div className="squircle/100 rounded-2xl bg-primary" />

      {/* Minimal smoothing (closer to a plain rounded rectangle) */}
      <div className="squircle/20 rounded-2xl bg-primary" />

      {/* Arbitrary smoothing */}
      <div className="squircle/[0.25] rounded-2xl bg-primary" />
    </>
  )
}

3. Native Borders & Backgrounds (The Magic)

Unlike basic CSS masks, the Houdini worklet reads your native CSS border and background classes and draws them flawlessly.

export default function SpaceUI() {
  return (
    <div>
      {/* 8px red border perfectly drawn onto the squircle shape */}
      <div className="squircle rounded-2xl border-8 border-red-500 bg-black" />
      {/* 1px semi-transparent blue border */}
      <div className="squircle rounded-[30px] border border-blue-500/50 bg-white" />
    </div>
  )
}

Note on border placement: By default, the plugin draws the border outside the element (like an outline or a ring) to preserve the interior space for your content. If you want the border drawn inward (standard CSS border-box behavior), you can override the custom CSS variable: <div className="squircle rounded-2xl border-4 border-red-500">...</div>