Forem: Giovambattista Fazioli

FinderGit v0.1.0 — Stop Tabbing Between Finder and Your Git Client

Giovambattista Fazioli — Wed, 15 Apr 2026 16:07:20 +0000

A day with twelve repositories

Before. You have a ~/Projects folder with twelve Git repos in it. To know which ones are dirty, you open Terminal, cd into each, run git status, repeat. Or you open Tower and wait for it to scan. Or you open VS Code twelve times. None of this is looking at your files — it's ceremony around looking at your files.

After. You open FinderGit and the folder tree looks like Finder's list view, plus four columns: branch name, clean/dirty/unpushed badge, number of changed files, and sizes and dates. Directories inside a dirty repo get a small orange dot with a count — so you spot modifications three levels deep without expanding anything.

That's the whole pitch. The rest of this post is the details.

What is FinderGit?

FinderGit is a native macOS app built with SwiftUI. It's positioned somewhere between Finder and a heavy Git client like Tower — it's not a replacement for either. If your day involves interactive rebases, submodule surgery, or cherry-picking across a long history, you'll still want Tower, GitX, or your CLI.

FinderGit is for the other 90% of the day: the part where you're browsing your projects, quickly checking "what did I leave dirty yesterday?", staging a few files, typing a commit message, pushing. Everything happens in the window that already shows your files — no context switch.

It runs on macOS 15 Sequoia or later. It's free, open-source (the website repo is public, the app repo will follow), and this is the public beta — v0.1.0. Expect a few rough edges; file them, I fix them.

✨ Key features

Tree view with sortable columns — Finder-style list view, but the columns are Name, Branch, Status, Changes, Size, Date Modified. Click any header to sort.
Live Git status per repository — a small badge next to each repo: CLEAN (green), DIRTY (orange), UNPUSHED (blue). Updates in real time via FSEvents.
Sub-directory dirty indicators — directories inside a repo show an orange dot with the number of modified files they contain. Walk down to the changes without expanding every folder.
Inline diff viewer — click any modified file and the right pane renders a unified diff with green/red lines, hunk headers, and line numbers. Supports HEAD, staged, unstaged, and even untracked files (rendered as all-added).
Git actions from the UI — Stage, Unstage, Commit, Push, Pull, Fetch. Per file or per repo. Commit messages get a TextField and two buttons: Commit Staged or Commit All & Push.
Native Markdown preview via Quick Look — press Space on any .md or .markdown file and it opens in a native renderer with a GitHub-style theme. Close with Space or Escape. Every other file type falls back to the system qlmanage, so you keep PDF, image, video previews for free.
Smart context menus — right-click adapts to what you clicked: repo gets Fetch / Pull / Push / Stage All; tracked file gets Stage / Unstage; non-git directory gets Add as Root Folder; everything gets Open / Reveal in Finder / Copy Path / Open in Terminal.
Multiple root folders — add as many as you want. Drop folders from Finder directly onto the sidebar; they become tree roots.
Search & filter — type in the toolbar to filter the tree by name (300ms debounce). Toggle Git Only to hide everything that isn't a repo — instant overview of just your projects.
Keyboard-driven — ⌘⇧F Fetch, ⌘⇧L Pull, ⌘⇧P Push, ⌘⇧A Stage All, ⌘⇧S Stage selected, Space Quick Look, ⌘+/⌘- zoom, ⌘⇧R Reveal in Finder. The usual Mac muscle memory.

🛠 What's powering it

For the developer-curious reader:

Swift + SwiftUI, deployment target macOS 15. The UI uses NavigationSplitView with a native Table(children:) for the tree, so sorting, keyboard navigation and selection come from AppKit under the hood.
Observation framework (@Observable) for state — no ObservableObject / @Published boilerplate. Structured concurrency (async/await) everywhere, no DispatchQueue.
FSEvents via a small GitWatcher that observes both the worktree and .git/HEAD, .git/index, .git/refs/, .git/FETCH_HEAD — debounced at the user-configurable latency. So pushing in Terminal updates the FinderGit badge within milliseconds.
git status --porcelain=v2 under the hood. /usr/bin/git is called via Process with a parser for the machine-readable output. No libgit2, no reimplementing history — the real git binary is the source of truth.
MarkdownUI for the Markdown preview. Pattern is extensible — same "interceptor" will take .css / .js / .swift with syntax highlighting in a future release.
Sparkle for auto-updates, EdDSA-signed. See below.
Personal Team signing, no Apple Developer Program ($99/year) required. That has implications for Gatekeeper — covered in the install section.

📦 Install

Requirements

macOS 15 (Sequoia) or later
Xcode Command Line Tools — FinderGit uses the system git binary, which on macOS is shipped as a stub. On a fresh Mac, run once:

  xcode-select --install
  sudo xcodebuild -license

Without these, every Git action inside FinderGit returns nonZeroExit(status: 89, …). This will be surfaced as a friendly dialog in a future release — for now, the Terminal workaround is a one-time setup.

Download

Grab the latest .dmg from the GitHub Release.
Open it and drag FinderGit into your Applications folder.

First launch — Gatekeeper

The app is signed with a free Personal Team, not with an Apple Developer ID. That means macOS Gatekeeper doesn't know it and will block the first launch with a generic warning. The fix is the standard Mac dance:

Open Applications in Finder.
Right-click on FinderGit.app → Open.
In the confirmation popup, click Open again.

Done once — from then on the app launches normally, including auto-updates. No paid developer program is funding this; you're trading a 5-second first-launch gesture for a free app.

🔄 Auto-updates

FinderGit ships with Sparkle. The app checks https://findergit.app/appcast.xml on launch and periodically; when a new version is available, you get the standard Sparkle alert with release notes. Each release DMG is signed with an EdDSA key — the public key ships inside the app, so Sparkle refuses to install an update it cannot verify. Even if my GitHub account were compromised tomorrow, an attacker couldn't push a malicious update without my private signing key.

You can also trigger a check manually via the FinderGit → Check for Updates… menu item.

🗺 What's next

The beta is functional, but plenty is already planned. Highlights of the public issue tracker:

Syntax highlighting in Quick Look for code files (.swift, .js, .ts, .py, .css, .json, …) — the Markdown interceptor pattern, extended.
Double-click a folder to navigate into it (drill-down, with a breadcrumb to go back).
Branch creation, renaming, deletion, checkout from the UI.
Stash management (save, pop, apply, drop).
GitHub / GitLab / Bitbucket providers — list Issues and Pull Requests for the current repo. Preference for gh / glab CLI when installed; REST fallback with a token in Keychain.
Kaleidoscope integration — jump from the inline diff to the full Kaleidoscope comparison, à la Tower.
diny integration for AI-generated commit messages, right next to the commit text field.
Auto-fetch on an interval wired to the setting that already exists.
Drag files from the tree to external apps — without breaking row selection, which is why it's not in v0.1.0.

If any of these are on your wish list, say so — priorities move.

Download, feedback, sponsorship

Three things, in order of how much they help:

Download it and try it → latest release. Ten minutes with real repos tells you more than any blog post.
Tell me what works and what doesn't → open an issue on the website repo. Bug reports, feature requests, workflow pain points — all welcome. Screenshots help.
If it turns into something you rely on, consider sponsoring → GitHub Sponsors. FinderGit is free, unsigned by Apple, and maintained in evenings and weekends. Sponsorship keeps the momentum.

WP Bannerize Pro v1.13.0 — Your Banners Just Got Sharper, Safer, and More Flexible

Giovambattista Fazioli — Sat, 11 Apr 2026 12:53:31 +0000

WebP support, 6 security hardening fixes, responsive flexbox layouts, and PHP 7.4 compatibility — the biggest quality release yet.

Introduction

A user asked: "Would it be possible to consider adding support for WebP banners?" — and that request kicked off a deep dive into the entire codebase. What started as a simple format addition turned into a comprehensive quality release: 6 security hardening fixes, 9 bug fixes, a complete layout redesign, and full PHP 7.4 compatibility. Whether you've been running Bannerize for years or you're evaluating it for the first time, v1.13.0 is the most solid release we've shipped.

What's New in 1.13.0

✨ WebP Image Support

The most requested feature is here. You can now create banners using WebP images — both from your WordPress media library and from external URLs. WebP delivers significantly smaller file sizes than JPEG or PNG at comparable quality, which means faster page loads and better Core Web Vitals scores for your site.

No configuration needed — just upload a .webp file or paste a WebP URL, and Bannerize handles the rest. The format is fully supported across the media library picker, remote image validation, and banner rendering.

🔒 Security Improvements

This release includes 6 targeted security hardening fixes across the analytics and query systems:

All analytics database queries now use parameterized placeholders instead of string interpolation
The banner query builder uses prepared statements for all meta key joins
SQL export functions properly escape table names
Admin error notices are restricted to users with the correct capabilities

These are proactive hardening measures — we identified and fixed these patterns during a comprehensive code review. Your site data has always been safe, and now the code follows WordPress security best practices even more strictly.

🐛 Bug Fixes That Matter

For everyone:

The Gutenberg block now works correctly with the WordPress REST API (fixed a missing schema type that caused console warnings)
Banner layouts respect the layout parameter properly — horizontal actually means horizontal now
Banners with null campaign assignments no longer crash the data tables

For developers on PHP 7.4:

Removed a PHP 8.0-only function (str_starts_with) that could cause fatal errors on older PHP versions
The plugin is now verified compatible with PHP 7.4 through 8.3

For power users:

Max impressions and max clicks display correctly in the banner list columns
Image size detection failures no longer cause fatal errors during banner save

🚀 Responsive Layout Redesign

The banner display layout has been completely rewritten using modern CSS flexbox:

Horizontal layout: Banners automatically wrap into 2+ columns on wide screens and stack into a single column on mobile (below 600px)
Vertical layout: Consistent gap spacing between banners
All images: Fully responsive with max-width: 100% — no more overflow on small screens

The old float: left approach is gone. If you've been struggling with banner alignment on mobile devices, this update fixes it.

Getting Started

New to Bannerize? Install it directly from your WordPress dashboard:

Go to Plugins > Add New
Search for "WP Bannerize Pro"
Click Install Now, then Activate
Navigate to WP Bannerize in your admin sidebar to create your first banner

Already using Bannerize? Update from your WordPress dashboard — your banners, campaigns, and analytics data are fully preserved.

Built with WPBones

WP Bannerize Pro is built on the WPBones framework — a Laravel-style architecture for WordPress plugin development. WPBones provides IoC container, service providers, Blade templating, and modern development tools that make building robust WordPress plugins a pleasure.

👉 Learn more about WPBones | GitHub

Scotty v2.0.2 — Now Your Dashboard Tells You What to Clean

Giovambattista Fazioli — Sat, 11 Apr 2026 12:50:37 +0000

New Trash Summary and Environment Info cards, redesigned footer, smarter dashboard widget, dark mode fix, and full Italian translation.

Introduction

The best maintenance tool is one that tells you where to look before you start cleaning. Scotty v2.0.2 adds two new Overview cards — Trash Summary and Environment Info — that give you instant visibility into what needs attention and what's running under the hood. The dashboard widget got a complete rewrite with proper loading states and database metrics, the footer now credits the tools that power the plugin, and a dark mode bug that made confirm dialogs unreadable is finally fixed.

What's New in 2.0.2

✨ Trash Summary Card

The Overview now includes a Items to Clean card that shows the total number of cleanable items across your site at a glance. Colored badges break it down by category:

Revisions, auto-drafts, trashed posts, spam comments, orphan metadata
Each badge only appears when items exist — clean sites show a green zero
Click "Clean now" to jump directly to the Trash section

No more guessing how cluttered your database is — the number is right there on the dashboard.

✨ Environment Info Card

A new card in the Overview row displays your server configuration:

PHP version, WordPress version, MySQL version
Memory limit and max upload size
Server software (nginx, Apache, etc.)

This data loads with zero extra queries — it's pulled from the WordPress runtime at no performance cost. Useful for debugging, support tickets, or just knowing what you're running.

✨ Redesigned Footer

The plugin footer has been completely rewritten:

Left side: Docs link and Report Issue link with colored icons
Right side: "Built with WP Bones | Mantine UI" with framework logos
Clean, informative, and properly credits the open-source tools that power Scotty

✨ Smarter Dashboard Widget

The WordPress Dashboard widget has been rebuilt from the ground up:

Loading skeleton while data fetches (was blank before)
Error state with clear message if the API call fails
Database Size and Cron Jobs count in a compact footer row
Translated tooltips for all progress bars
19% smaller bundle — removed unused providers and CSS imports
Fixed link — "Open Scotty" now goes to Overview instead of Trash

🐛 Dark Mode Fix

The modal confirm dialog title was invisible in dark mode — black text on dark background. Now uses var(--mantine-color-text) which adapts to the color scheme automatically.

🌍 Italian Translation Update

All 223 translatable strings are now covered with 100% Italian translation, including the new Trash Summary, Environment Info, and footer text. POT, PO, MO, and JSON files all regenerated.

Getting Started

New to Scotty? Install from your WordPress dashboard:

Go to Plugins > Add New
Search for "Scotty"
Click Install Now, then Activate

Already using Scotty? Update from your WordPress dashboard. All your settings and data are preserved.

Built with WPBones

Scotty is built on the WPBones framework — a Laravel-style architecture for WordPress plugin development. The React dashboard is powered by Mantine UI, giving you a modern, fast, and accessible interface.

👉 Learn more about WPBones | GitHub

Magnify Your Choices: A Fisheye Select Component for Mantine

Giovambattista Fazioli — Thu, 09 Apr 2026 12:35:03 +0000

A select component where items magnify under your cursor -- macOS Dock-style -- built for Mantine 9.

The Problem With Flat Lists

You are building a settings panel where users pick a value from a range -- say, a volume level from 1 to 10, or a date from a multi-year timeline. A traditional <select> dropdown works, but it is buried behind a click. A slider works, but it carries no visual weight. What if the selection itself could respond to the user's intent -- items growing as the cursor approaches, then settling back as it moves away?

That is exactly what @gfazioli/mantine-lens-select does. It brings the macOS Dock's fisheye magnification effect to a Mantine select component, making selection both functional and delightful.

What Is LensSelect?

LensSelect is a React component built on top of Mantine 9 that displays a row (or column) of items with a cosine-based lens magnification effect on hover. Items near the cursor scale up smoothly while distant items remain at their base size, creating an interactive and visually engaging selection experience.

It ships as @gfazioli/mantine-lens-select v1.0.0, follows the full Mantine Factory pattern, and supports the Styles API out of the box.

Key Features

Pill Mode -- Zero Configuration

The simplest usage needs no data array at all. Just pass a count and you get styled pills with automatic numeric values:

import { LensSelect } from '@gfazioli/mantine-lens-select';

function Demo() {
  return <LensSelect count={20} />;
}

Twenty rounded vertical bars appear, each responding to your cursor with the fisheye effect. The active pill gets the primary color, hovered pills get a lighter tint, and a dot indicator tracks the selection.

Count Mode with Ranges

For numeric selection, combine count with min/max to generate evenly distributed values, or use step for fixed increments -- an API that will feel familiar if you have used Mantine's Slider:

// 20 pills mapped linearly from 0 to 100
<LensSelect count={20} min={0} max={100} />

// Fixed steps: pills at 0, 10, 20, ..., 100
<LensSelect min={0} max={100} step={10} />

// Decimal precision: 0.00, 0.25, 0.50, 0.75, 1.00
<LensSelect min={0} max={1} step={0.25} precision={2} />

The data prop always takes priority, so you can start with count mode during prototyping and switch to a custom data array later without changing anything else.

Custom Data with Rich Content

Pass an array of { value, view } objects for full control over what each item renders:

const apps = [
  { value: 'finder', view: <span>📁</span> },
  { value: 'safari', view: <span>🧭</span> },
  { value: 'mail', view: <span>📧</span> },
  { value: 'settings', view: <span>⚙️</span> },
];

<LensSelect data={apps} itemSize={48} magnification={2.5} expandOnHover />

When view is omitted from all items, the component automatically enters pill mode -- no special flag needed.

Orientation: Horizontal and Vertical

Switch between horizontal and vertical layouts with a single prop. Vertical mode is perfect for timeline selectors:

<LensSelect
  data={events}
  orientation="vertical"
  itemSize={12}
  gap={6}
  pillWidth={2}
  activeColor="orange"
/>

Visual Effects Stack

Three independent visual effects can be combined:

Scale (withScale) -- the core fisheye magnification, enabled by default
Opacity (withOpacity) -- distant items fade, focused items stay opaque
Blur (withBlur) -- distant items blur, focused items stay sharp

Each effect has configurable ranges (opacityRange, blurRange) and all respect the same cosine-based falloff curve controlled by magnification and lensRange.

Expand on Hover

Enable expandOnHover to make items push their neighbors apart during magnification -- the signature macOS Dock behavior:

<LensSelect
  count={15}
  itemSize={48}
  magnification={2.5}
  expandOnHover
  transitionDuration={0}
  easing="linear"
/>

Selection Modes and Navigation

Two selection modes serve different use cases:

Click mode (default) -- user clicks to select
Hover mode -- selection follows the cursor automatically

On top of that, LensSelect supports:

Keyboard navigation -- Arrow keys, Home, End with proper orientation awareness
Mouse wheel -- scroll through items with withWheel
Loop -- wrap around from last to first (and vice versa) with loop
Touch -- swipe navigation on mobile devices

The Indicator: A Compound Component

LensSelect.Indicator is a compound sub-component that renders a tracking dot below (or beside, in vertical mode) the active item. It follows the item in real time using requestAnimationFrame, staying in sync even during magnification animations.

Use it automatically via the withIndicator prop, or mount it explicitly as a child for full control:

<LensSelect data={data} withIndicator={false}>
  <LensSelect.Indicator
    variant="outline"
    color="red"
    size={10}
    offset={20}
  />
</LensSelect>

Both LensSelect and LensSelect.Indicator support default and outline variants independently, so you can mix filled pills with an outline indicator dot (or vice versa).

renderItem for Total Control

When pills and view are not enough, renderItem gives you a callback with the item, its active state, current scale factor, and hover status:

<LensSelect
  data={apps}
  renderItem={(item, { active, scale, hovered }) => (
    <Box
      style={{
        borderRadius: 10,
        background: active ? 'var(--mantine-color-blue-6)' : 'var(--mantine-color-gray-1)',
        fontSize: 24,
      }}
    >
      {item.view}
    </Box>
  )}
/>

Getting Started

Install the package:

npm install @gfazioli/mantine-lens-select
# or
yarn add @gfazioli/mantine-lens-select

Import styles at the root of your application:

import '@gfazioli/mantine-lens-select/styles.css';

Layer-aware import is also available:

import '@gfazioli/mantine-lens-select/styles.layer.css';

Then use it:

import { LensSelect } from '@gfazioli/mantine-lens-select';

function App() {
  const [value, setValue] = useState(5);

  return (
    <LensSelect
      count={10}
      value={value}
      onChange={setValue}
    />
  );
}

Props and API at a Glance

Core props:

Prop	Type	Default	Description
`data`	`LensSelectItem[]`	--	Array of `{ value, view? }` items
`count`	`number`	--	Generate N pills with numeric values (no data needed)
`min` / `max`	`number`	--	Range bounds for generated values
`step`	`number`	--	Fixed increment between generated values
`precision`	`number`	`0`	Decimal places for generated values
`value` / `defaultValue`	`string \	number`	--
`onChange`	`(value) => void`	--	Selection change callback
`orientation`	`'horizontal' \	'vertical'`	`'horizontal'`
`magnification`	`number`	`2`	Maximum scale factor (200%)
`lensRange`	`number`	`3`	Number of adjacent items influenced
`expandOnHover`	`boolean`	`false`	Push neighbors apart (Dock behavior)
`selectionMode`	`'click' \	'hover'`	`'click'`
`withWheel`	`boolean`	`false`	Enable scroll wheel navigation
`loop`	`boolean`	`false`	Wrap-around navigation
`variant`	`'default' \	'outline'`	`'default'`

Visual effects: withScale, withOpacity, withBlur, opacityRange, blurRange

Pill styling: itemSize, gap, pillWidth, pillHeight, pillRadius, pillColor, hoverColor, activeColor

Transitions: transitionDuration, easing (linear, ease-out, ease-in-out, spring, or custom cubic-bezier)

Styles API: 6 selectors (root, track, item, itemContent, itemPill, indicator) and 12 CSS custom properties for full visual customization.

Advanced Usage

macOS Dock Recreation

Combine renderItem, expandOnHover, and a Paper container for a faithful Dock clone:

<Paper px="lg" pt="md" pb="sm" radius="lg" withBorder
  style={{ backdropFilter: 'blur(20px)' }}>
  <LensSelect
    data={apps}
    itemSize={48}
    gap={4}
    magnification={2.5}
    lensRange={3}
    expandOnHover
    transitionDuration={0}
    easing="linear"
    renderItem={(item, { active }) => (
      <Box style={{
        borderRadius: 10,
        background: active
          ? 'var(--mantine-color-blue-6)'
          : 'var(--mantine-color-gray-1)',
        fontSize: 24,
      }}>
        {item.view}
      </Box>
    )}
    indicatorProps={{ size: 4, offset: 8 }}
  />
</Paper>

Weekday Picker with Dynamic Colors

Leverage controlled state to change colors based on the selected value:

function WeekdayPicker() {
  const [day, setDay] = useState('Mon');
  const isWeekend = day === 'Sat' || day === 'Sun';

  return (
    <LensSelect
      data={DAYS}
      value={day}
      onChange={setDay}
      itemSize={36}
      magnification={1.8}
      lensRange={2}
      activeColor={isWeekend ? 'red' : 'blue'}
      indicatorProps={{ color: isWeekend ? 'red' : 'blue' }}
    />
  );
}

Volume / Rating Selector

A compact numeric selector with count mode -- no data array required:

function VolumeControl() {
  const [volume, setVolume] = useState(5);

  return (
    <LensSelect
      count={10}
      value={volume}
      onChange={setVolume}
      itemSize={32}
      gap={3}
      pillWidth={6}
      magnification={1.5}
      lensRange={2}
      activeColor="teal"
      hoverColor="teal"
      indicatorProps={{ color: 'teal', size: 4 }}
    />
  );
}

Vertical Timeline

Use vertical orientation for a time-machine-style date navigator:

const events = [2022, 2023, 2024, 2025].flatMap((year) =>
  months.map((month) => ({ value: `${month} ${year}` }))
);

<LensSelect
  data={events}
  orientation="vertical"
  itemSize={12}
  gap={6}
  pillWidth={2}
  magnification={1.5}
  lensRange={2}
  activeColor="orange"
  indicatorProps={{ color: 'orange', size: 5, offset: 12 }}
/>

Accessibility

LensSelect implements the WAI-ARIA listbox pattern:

role="listbox" on the root, role="option" on each item
aria-selected reflects the current selection
aria-orientation matches the layout direction
Full keyboard navigation: Arrow keys (orientation-aware), Home, End
prefers-reduced-motion media query disables all CSS transitions
Configurable ariaLabel prop

Under the Hood

A few implementation details worth noting:

Cosine-based falloff: the lens effect uses (1 + cos(pi * distance / maxRange)) / 2 for a smooth bell-curve that feels natural rather than linear
CSS-native responsive props: itemSize, gap, pillWidth, and pillHeight all support Mantine's StyleProp responsive syntax via InlineStyles + CSS media queries -- no useMatches re-renders
GPU-optimized: will-change is set only during active hover and removed on mouse leave
RAF-synced indicator: the dot position updates via requestAnimationFrame to stay in sync with CSS transitions

Live Demo

Try the interactive configurator and all use-case demos on the documentation site:

gfazioli.github.io/mantine-lens-select

I Built a Shared Library for the Amiga in 68020 Assembly — and a Modern Documentation Site for It

Giovambattista Fazioli — Wed, 08 Apr 2026 09:50:11 +0000

Back in 1991, I started writing what would become a 5,800-line shared library for the Commodore Amiga — entirely in hand-optimized Motorola 68020 assembly. The first routines (string utilities in libraries.asm) were saved on July 29, 1991. Over the next four years, the library grew steadily — graphics in October 1994, file I/O and memory management in early 1995, the REI windowing system through mid-1995, and the last recorded update in September 1995.

That code sat on floppy disks and hard drives for decades. Now, in 2026, I've dusted it off, open-sourced it, and built a modern documentation site for it with Next.js.

Let me tell you the story.

What Is This?

The Amiga Assembly Library is a shared library (assembly.library) for AmigaOS, written between 1991 and 1995, that provides 50+ high-level utility functions in optimized 68020 assembly. Think of it as a "standard library" for Amiga developers — covering everything from memory management and file I/O to bitmap graphics, string manipulation, and even a full windowing abstraction.

It's Public Domain — no copyright, no licensing, no restrictions. Use it however you want.

Why Assembly? And Why Now?

When I wrote this library in the early '90s, the Amiga was my daily machine. I was 19, obsessed with squeezing every cycle out of the 68020, and frustrated by rewriting the same utility routines for every project. So I did what any obsessive programmer would do — I built a shared library.

The Amiga community, remarkably, is still alive and well in 2026. People are building hardware accelerators, writing new software, and pushing these machines beyond what anyone thought possible. When you're working with a 7 MHz 68000 (or a 50 MHz 68060 if you're lucky), every cycle counts. Hand-optimized assembly isn't a flex — it's a necessity.

I decided to open-source the library and give it the documentation it always deserved — because if this code helped me build a dozen projects in the '90s, maybe it can help someone else today.

What's Inside?

The library is organized into 8 modules:

Exec — Memory and linked list management. AllocNewList, AllocNode, FreeList, ReAllocVec, and RevertMem for reversing memory regions.

DOS — File operations. Load and Save files to/from memory, FileInfo for metadata, CheckSum for data integrity, LineInput for reading files line by line, and UnitInfo for volume information.

Graphics — Bitmap rendering. Allocate and clone RastPorts, manage bitplanes dynamically, draw boxes and frames, and render printf-style formatted text directly to graphics surfaces.

Libraries — String utilities and media parsing. Case conversion, character filtering, AIFF/IFF chunk parsing, and ILBM image decompression.

Math — Number conversions between decimal, hex, binary strings and values — in both directions.

Intuition & GadTools — UI widgets. Custom dialog requesters with buttons, gadget property control by name (not just ID), and attribute manipulation.

REI Interface — This is the crown jewel. A complete windowing abstraction that separates UI definitions from application logic. You define your window layout in a .rei binary file, load it at runtime, and interact with named gadgets through an event-driven message loop. Think of it as a declarative UI system — for a 1990s computer.

C Interface — Full C prototypes and SAS/C pragma declarations so you can call every function from C with type safety.

The Magic of Auto-Opening

One of my favorite design decisions: when you open assembly.library, it automatically opens and caches 12+ system libraries for you:

#include <assembly/assemblybase.h>
#include <clib/assembly_protos.h>

struct AssemblyBase *AssemblyBase;

void main(int argc, char **argv)
{
    if (AssemblyBase = (struct AssemblyBase *)
        OpenLibrary(ASSEMBLYNAME, ASSEMBLY_MINIMUM))
    {
        /* All sub-libraries are now available:
         * AssemblyBase->ab_DosBase
         * AssemblyBase->ab_IntuiBase
         * AssemblyBase->ab_GfxBase
         * AssemblyBase->ab_GadToolsBase
         * AssemblyBase->ab_AslBase
         * ... and 7 more
         */

        CloseLibrary((struct Library *)AssemblyBase);
    }
}

One OpenLibrary call and you get graphics.library, intuition.library, dos.library, gadtools.library, asl.library, icon.library, workbench.library, datatypes.library, locale.library, lowlevel.library, realtime.library — all ready to use. No boilerplate. No forgetting to close one of them.

The REI Windowing System

The REI (Runtime External Interface) module deserves its own section. Instead of hardcoding window layouts in your application code, you define them in .rei files — binary interface definitions that describe windows, gadgets, menus, and their relationships.

At runtime, you load the .rei file and interact with UI elements by name:

OpenREI          → Create the window from a .rei file
WaitREIMsg       → Event-driven message loop
FindAsmGadget    → Find a gadget by its name
SetREIAttrs      → Change window properties
LockREI/UnlockREI → Thread-safe access
CloseREI         → Clean shutdown

The project even includes a visual REI Editor (v0.52) — a GUI tool for designing .rei files without writing code.

This approach is philosophically similar to what modern frameworks do with JSX or XML layouts. But this was designed for AmigaOS, running on a 68020.

The Documentation Site

Here's where old meets new. The library documentation lives at amiga-assembly-library.vercel.app — a modern site built with:

Next.js 15 with Nextra for MDX-based docs
Mantine 9 for the UI components
TypeScript 6 for type safety
Syntax-highlighted 68020 assembly source code
Complete API reference for all 50+ functions
Example programs with full source
An Amiga Mode toggle that applies retro styling

Yes, a documentation site built with React and TypeScript — for a 68020 assembly library. The irony is not lost on me.

Getting Started

Requirements

CPU: Motorola 68020 or higher
OS: AmigaOS with KickStart 3.0 (V39) or later
Assembler: HiSoft DevPac or compatible
C Compiler (optional): SAS/C, DICE, or compatible

Installation

Copy assembly.library to your LIBS: directory. That's it — it's a standard AmigaOS shared library, available system-wide to all applications.

Assembly Usage

        move.l  _AbsExecBase,a6
        lea     AssemblyName(pc),a1
        moveq   #ASSEMBLY_MINIMUM,d0
        jsr     _LVOOpenLibrary(a6)
        move.l  d0,_AssemblyBase
        beq     .error

        ; Use library functions...
        move.l  _AssemblyBase,a6
        jsr     _LVOAllocNewList(a6)

        ; Clean up
        move.l  _AbsExecBase,a6
        move.l  _AssemblyBase,a1
        jsr     _LVOCloseLibrary(a6)

C Usage

Include the headers, open the library, and call functions directly:

#include <assembly/assemblybase.h>
#include <clib/assembly_protos.h>
#pragma libcall AssemblyBase AllocNewList 1e 00

struct List *myList = AllocNewList();

What's in the Source?

The library is about 5,800 lines of hand-optimized 68020 assembly across 8 modules:

Module	Lines	What it does
`intui-gadtools.asm`	2,016	UI widgets and requesters
`rei.asm`	1,990	The REI windowing system
`graphics.asm`	539	Bitmap and drawing functions
`libraries.asm`	347	Strings and media parsing
`math.asm`	314	Number conversions
`dos.asm`	278	File I/O operations
`exec.asm`	232	Memory and list management
`section.asm`	135	Library initialization

Plus C headers, pragma declarations, example programs (including a screen grabber, a window inspector, and the visual REI editor), and comprehensive documentation.

Why Open Source This?

Because the Amiga community thrives on sharing. The best Amiga software was always the stuff people passed around on floppy disks, uploaded to Aminet, and shared freely. This library is Public Domain — not MIT, not GPL, not Apache. Public Domain. Take it, use it, modify it, sell it, whatever you want. No attribution required.

If even one person building an Amiga project finds a useful function in here, it was worth it.

Links

Documentation: amiga-assembly-library.vercel.app
Source Code: github.com/gfazioli/Assembly-Library
Documentation Source: github.com/gfazioli/amiga-assembly-library

This code is over 30 years old. I wrote it when I was a teenager, on a machine with 2 MB of RAM. And somehow it still works, still compiles, and still does exactly what it was designed to do. There's something deeply satisfying about that.

If you're into retro computing, 68k assembly, or just appreciate the craft of writing software for constrained platforms — I'd love to hear from you. Drop a star on the repo, open an issue, or just say hi.

The Amiga isn't dead. It's just warming up.

Selection Through the Looking Glass: A 3D Stack Component for Mantine

Giovambattista Fazioli — Sat, 28 Mar 2026 08:51:39 +0000

A Mantine component that turns flat item selection into a spatial, 3D card-stack browsing experience — with keyboard, wheel, touch, and click navigation built in.

Introduction

Remember the first time you used macOS Time Machine? That moment when your desktop peeled away into an infinite corridor of snapshots, and navigating through time suddenly felt physical. That spatial metaphor stuck with us. mantine-depth-select brings that same sense of depth to any selection UI in your React application — pricing plans, document versions, onboarding steps, or anything else where browsing through stacked content beats scrolling a flat list. It's a single component with zero extra dependencies, built entirely on Mantine 8's Styles API.

What is DepthSelect?

DepthSelect renders an array of items as a 3D stack of cards. The frontmost card is the active selection; cards behind it recede with progressive scale, vertical offset, opacity, and blur — all configurable per-level. When the user navigates (via keyboard, mouse wheel, trackpad swipe, click, or arrow controls), cards animate smoothly in and out of the stack with CSS transitions.

The component follows Mantine's compound component pattern. Built-in arrow controls appear by default, but you can hide them and wire up your own UI through controlled value/onChange. It supports both string and numeric values, loop mode, and respects prefers-reduced-motion.

✨ Key Features

3D Perspective Stack

Each card in the stack receives progressive CSS transforms based on its depth. Four props control the effect:

<DepthSelect
  data={items}
  scaleStep={0.1}       // scale reduction per level (default)
  translateYStep={30}    // vertical offset in px per level
  opacityStep={0.15}     // opacity reduction per level
  blurStep={1}           // blur in px per level
  w={400}
  h={300}
/>

Cards that exit the stack (when navigating forward) animate toward the viewer with a scale-up and fade-out. Cards entering from behind animate in from the deepest visible position.

Multi-Input Navigation

Every common input method works out of the box:

Keyboard: ArrowUp/ArrowDown to step through, Home/End to jump
Mouse wheel / Trackpad: Scroll over the component to navigate (page scroll is blocked automatically). Disable with withScrollNavigation={false}
Touch: Vertical swipe gestures for mobile
Click: Click the second card (depth 1) to advance
Controls: Built-in arrow buttons with optional label

Built-in Controls with `controlsProps`

The default controls sit to the right of the stack. You can reposition them, add a label, set a fixed width, change alignment, or swap the icons — all through a single controlsProps object:

<DepthSelect
  data={items}
  controlsPosition="left"
  controlsProps={{
    w: 100,
    justify: 'end',
    labelFormatter: (item) => `Step ${item.value}`,
    upIcon: <IconChevronUp size={16} />,
    downIcon: <IconChevronDown size={16} />,
  }}
  w={400}
  h={300}
/>

Compound Component Pattern

Need full layout control? Set withControls={false} and use DepthSelect.Controls as a child:

<DepthSelect data={items} withControls={false} w={400} h={300}>
  <DepthSelect.Controls labelFormatter={(item) => String(item.value)} />
</DepthSelect>

Or skip the built-in controls entirely and build your own navigation with value and onChange.

Loop Mode

Enable loop to let navigation wrap from the last item back to the first (and vice versa). The arrow controls never show a disabled state in loop mode:

<DepthSelect data={items} loop w={400} h={200} />

🚀 Getting Started

npm install @gfazioli/mantine-depth-select

Import the styles at the root of your application:

import '@gfazioli/mantine-depth-select/styles.css';

Minimal example:

import { Card, Text } from '@mantine/core';
import { DepthSelect, DepthSelectItem } from '@gfazioli/mantine-depth-select';

const data: DepthSelectItem[] = [
  { value: 'first', view: <Card p="lg" withBorder h="100%"><Text>First item</Text></Card> },
  { value: 'second', view: <Card p="lg" withBorder h="100%"><Text>Second item</Text></Card> },
  { value: 'third', view: <Card p="lg" withBorder h="100%"><Text>Third item</Text></Card> },
];

function Demo() {
  return <DepthSelect data={data} w={400} h={200} />;
}

The w and h props define the area where cards live. Cards should use h="100%" to fill the available height.

Props & API

DepthSelect

data — DepthSelectItem[] — Array of { value, view } objects. value can be string or number, view is any ReactNode
value / defaultValue / onChange — Standard controlled/uncontrolled pattern
w / h — Dimensions of the card area (passed to the inner stack container)
visibleCards — Number of cards visible in the stack (default: 4)
withControls — Show built-in arrow controls (default: true)
controlsPosition — "right" (default) or "left"
controlsProps — All DepthSelectControlsProps passed to the built-in controls
loop — Enable wrap-around navigation (default: false)
withScrollNavigation — Enable mouse wheel / trackpad navigation (default: true)
transitionDuration — Animation duration in ms (default: 400)
scaleStep / translateYStep / opacityStep / blurStep — Per-level depth effect parameters

DepthSelect.Controls

labelFormatter — (item: DepthSelectItem) => ReactNode — Custom label between arrows
upIcon / downIcon — Custom icons for the arrow buttons
justify — Vertical alignment: "start", "center" (default), "end"
Plus all Mantine BoxProps (w, h, style, etc.)

🎨 Styles API

Selectors: root, stack, card, controls, controlUp, controlDown, controlLabel

Data attributes:

data-active — Frontmost (selected) card
data-depth="N" — Card depth level (0 = front)
data-exited — Card that has animated out
data-disabled — Disabled control button
data-controls-position — "right" or "left" on root

CSS variables: --ds-transition-duration, --ds-scale-step, --ds-translate-y-step, --ds-opacity-step, --ds-blur-step, --ds-visible-cards

⚡ Performance

Render window: Only activeIndex - 1 through activeIndex + visibleCards + 1 are in the DOM. A dataset of 100 items renders ~6 nodes
Memoized styles: Card CSS is computed once per navigation change via useMemo
Targeted will-change: Only visible cards get GPU layer promotion; hidden cards use will-change: auto
Non-passive wheel listener: Blocks page scroll without layout thrashing
prefers-reduced-motion: Transitions are disabled automatically for users who prefer reduced motion

Live Demo & Documentation

Explore interactive demos — including a configurator with live props, rich card examples, pricing plan selector, version history browser, onboarding wizard, and more:

gfazioli.github.io/mantine-depth-select

Mantine SelectStepper 2.0.0 — Swipe, Scroll, Resize, Repeat

Giovambattista Fazioli — Wed, 25 Mar 2026 16:31:15 +0000

Vertical orientation, touch gestures, responsive props, imperative API, and 9 bug fixes — all in one major release.

Introduction

This release started with a one-line CSS fix from a community contributor: wrap="nowrap". That PR from @kruschid — just a single prop addition — exposed a deeper truth: SelectStepper v1 wasn't ready for the real world. Narrow containers broke it. Touch devices couldn't use it. Vertical layouts weren't possible. And the animation engine had a race condition hiding in plain sight. So instead of patching, we rebuilt — keeping the same API surface but rearchitecting the internals to handle every scenario we'd been ignoring. The result is v2.0.0: the same component, but now it actually works everywhere.

✨ What's New

Vertical Orientation

Flip the stepper on its side. Navigation buttons switch to up/down arrows, keyboard keys remap automatically, and swipe gestures respond to vertical movement.

<SelectStepper
  data={['XS', 'S', 'M', 'L', 'XL']}
  orientation="vertical"
  label="Size"
/>

The orientation prop is also responsive — vertical on mobile, horizontal on desktop:

<SelectStepper
  orientation={{ base: 'vertical', sm: 'horizontal' }}
  data={['XS', 'S', 'M', 'L', 'XL']}
/>

Swipe & Touch Gestures

Native Pointer Events — no external dependencies. Swipe left/right in horizontal mode, up/down in vertical. Enabled by default with a configurable threshold.

<SelectStepper
  data={['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday']}
  swipeable            // true by default
  swipeThreshold={30}  // pixels
  loop
/>

Imperative API

Control the stepper programmatically via controlRef. Navigate, reset, or jump to any value from parent code.

const controlRef = useRef<SelectStepperRef | null>(null);

<SelectStepper
  controlRef={controlRef}
  data={['React', 'Vue', 'Angular', 'Svelte']}
/>

// From anywhere in the parent:
controlRef.current?.next();
controlRef.current?.prev();
controlRef.current?.reset();
controlRef.current?.navigateTo('Svelte');

Responsive Props (CSS-Native)

viewWidth, viewHeight, and size accept Mantine breakpoint objects. Under the hood, responsive values are resolved via InlineStyles with real CSS @media queries — the same pattern Mantine core uses in SimpleGrid and Grid. Zero React re-renders on resize.

<SelectStepper
  data={['React', 'Vue', 'Angular']}
  viewWidth={{ base: 120, sm: 180, md: 260 }}
  size={{ base: 'xs', sm: 'sm', md: 'md' }}
/>

Size Prop

Control the ActionIcon button size independently from xs to xl. Supports responsive breakpoint objects.

<SelectStepper data={data} size="lg" />
<SelectStepper data={data} size={{ base: 'xs', md: 'md' }} />

Animation Callbacks

Synchronize external logic with navigation transitions using onStepStart and onStepEnd.

<SelectStepper
  data={data}
  onStepStart={() => setAnimating(true)}
  onStepEnd={() => setAnimating(false)}
/>

Gradient Variant

Full gradient support for navigation buttons, consistent with Mantine's variant system.

<SelectStepper
  data={['Low', 'Medium', 'High', 'Ultra']}
  variant="gradient"
  gradient={{ from: 'indigo', to: 'cyan', deg: 45 }}
/>

Accessible Button Labels

Localize navigation button labels for screen readers.

<SelectStepper
  previousLabel="Vorheriges Element"
  nextLabel="Nächstes Element"
/>

New Props Summary

Prop	Type	Default	Description
`orientation`	`StyleProp<'horizontal' \	'vertical'>`	`'horizontal'`
`viewHeight`	`StyleProp<CSSProperties['height']>`	`36`	Viewport height in vertical mode
`size`	`StyleProp<MantineSize>`	`'sm'`	ActionIcon button size
`swipeable`	`boolean`	`true`	Enable touch/swipe navigation
`swipeThreshold`	`number`	`30`	Min swipe distance in pixels
`onStepStart`	`() => void`	—	Fired when animation starts
`onStepEnd`	`() => void`	—	Fired when animation ends
`controlRef`	`RefObject<SelectStepperRef \	null>`	—
`previousLabel`	`string`	`'Previous item'`	Aria label for prev button
`nextLabel`	`string`	`'Next item'`	Aria label for next button
`gradient`	`MantineGradient`	—	Gradient config for `variant="gradient"`

💥 Breaking Changes

`defaultValue={null}` no longer auto-selects

Before (v1): Passing defaultValue={null} auto-selected the first non-disabled item.
After (v2): defaultValue={null} means "no selection" — the component starts empty.

// If you relied on null to auto-select, just omit the prop:
<SelectStepper data={data} />  // ← auto-selects first item

`viewWidth` type changed to `StyleProp`

The prop now accepts responsive objects. TypeScript users who explicitly type viewWidth as CSSProperties['width'] will need to update to StyleProp<CSSProperties['width']>. Runtime behavior is backward compatible.

`onChange` timing changed

The callback is now properly wired through Mantine's useUncontrolled hook. If you had workarounds for stale-state issues in v1, they may no longer be needed.

🐛 Bug Fixes

Timeout race condition — Rapid clicks no longer orphan timers or cause setState on unmounted components
Controlled mode sync — External value changes during animation no longer cause visual glitches
Loop animation — Infinite scroll now consistently moves forward instead of reversing at the boundary
Narrow container wrapping — Navigation buttons no longer wrap to a new line (thanks @kruschid)
View shrinking misalignment — Resizing below viewWidth no longer misaligns the scroll offset
Stale data handling — Changing data while value references a removed item now auto-resets
Callback consistency — onStepStart only fires when navigation actually occurs; onLeftIconClick/onRightIconClick respect canGoPrev/canGoNext
Demo import typo — Styles API demo no longer references the wrong package

🔧 Improvements

Full ARIA Accessibility

The component now implements role="spinbutton" with complete attributes: aria-valuemin, aria-valuemax, aria-valuenow, aria-valuetext, aria-disabled, aria-label, and aria-labelledby. A hidden aria-live="polite" region announces value changes to screen readers.

Orientation-Aware Keyboard Navigation

Arrow keys are now direction-specific: ArrowLeft/ArrowRight in horizontal, ArrowUp/ArrowDown in vertical. No more confusing cross-axis navigation.

66 Tests (up from 2)

Comprehensive coverage across: navigation, keyboard, controlled/uncontrolled mode, loop, disabled items, empty data, swipe gestures (with PointerEvent polyfill), imperative API, responsive props, ARIA attributes, and animation callbacks.

Documentation Reorganized

Docs follow the Mantine standard: Installation → Usage → Core → Behavior → Visual → Advanced → Reference. Eight new interactive demos added.

📦 Installation

yarn add @gfazioli/mantine-select-stepper

Import styles at your app root:

import '@gfazioli/mantine-select-stepper/styles.css';

Or with CSS layers:

import '@gfazioli/mantine-select-stepper/styles.layer.css';

Compatibility: Mantine 8.x · React 18/19 · TypeScript 5.x · MIT License

🔗 Links

Mantine List View Table - From Table to Finder

Giovambattista Fazioli — Sat, 21 Mar 2026 11:10:13 +0000

Row selection, keyboard navigation, context menus, column visibility, dual resize modes, and 6 exported hooks — one release, zero compromises.

Introduction

Picture the macOS Finder: you click a file, Shift+click to select a range, right-click for a context menu, double-click a column divider to auto-fit, and hide columns you don't need. Now picture doing all of that in a React table component — with full Mantine integration and zero external dependencies. That's what @gfazioli/mantine-list-view-table 2.0.0 delivers. This isn't an incremental update; it's a rewrite that transforms a sortable table into a complete Finder-style list view, with every piece of logic extracted into reusable, publicly exported hooks.

What's New

✨ Row Selection

Select rows exactly like macOS Finder. Single click selects one row, Cmd/Ctrl+Click toggles, Shift+Click selects a range. Both single and multiple modes are supported, with controlled and uncontrolled state.

<ListViewTable
  columns={columns}
  data={data}
  rowKey="id"
  selectionMode="multiple"
  onSelectionChange={(keys, records) => setSelected(keys)}
  selectedRowColor="blue"
/>

Selected rows get a visible highlight that desaturates when the component loses focus — matching Finder's behavior pixel for pixel.

⌨️ Keyboard Navigation

When selectionMode is set, keyboard navigation activates automatically:

Key	Action
Arrow Up/Down	Move focus between rows
Enter	Activate row (`onRowActivate`)
Space	Toggle selection
Home / End	Jump to first / last row
Cmd/Ctrl+A	Select all (multiple mode)

<ListViewTable
  selectionMode="multiple"
  enableKeyboardNavigation
  onRowActivate={(record) => openFile(record)}
/>

🖱️ Context Menu

Right-click any row to show a context menu powered by Mantine's Menu component. The clicked row is automatically selected before the menu appears. You get Mantine's full accessibility, keyboard support, and dark mode out of the box.

<ListViewTable
  selectionMode="single"
  renderContextMenu={({ record }) => (
    <>
      <Menu.Item leftSection={<IconCopy size={14} />}>Copy</Menu.Item>
      <Menu.Item leftSection={<IconDownload size={14} />}>Download</Menu.Item>
      <Menu.Divider />
      <Menu.Item color="red" leftSection={<IconTrash size={14} />}>Delete</Menu.Item>
    </>
  )}
/>

👁️ Column Visibility

Hide and show columns programmatically or let users toggle them by right-clicking the table header. Supports both controlled and uncontrolled modes.

<ListViewTable
  hiddenColumns={['size', 'modified']}
  onHiddenColumnsChange={setHiddenColumns}
  enableColumnVisibilityToggle
/>

↔️ Dual Resize Modes

The new resizeMode prop gives you two column resize behaviors:

standard (default) — width is traded between the dragged column and its right neighbor. Total table width stays fixed. Great for fixed-width layouts.
finder — only the dragged column changes width. The table grows freely, just like Finder. Pair with Table.ScrollContainer for horizontal scrolling.

<ListViewTable enableColumnResizing resizeMode="finder" />

🎯 Double-Click Auto-Fit

Double-click any resize handle to auto-fit the column to its content — measured accurately using off-screen DOM clones. In standard mode, the adjacent column compensates to keep the total width constant.

🪝 6 Exported Hooks

Every piece of internal logic is now a standalone, reusable hook:

Hook	Purpose
`useSorting`	Sort state with controlled/uncontrolled modes
`useColumnReorder`	Drag-and-drop column reordering
`useColumnResize`	Column resize with standard/finder modes
`useRowSelection`	Row selection (single, multiple, range)
`useKeyboardNavigation`	Arrow/Enter/Space keyboard navigation
`useColumnVisibility`	Column show/hide management

Import them directly for advanced compositions:

import { useRowSelection, useKeyboardNavigation } from '@gfazioli/mantine-list-view-table';

📋 New Props Summary

Prop	Type	Default	Description
`selectionMode`	`'single' \	'multiple'`	—
`selectedRows`	`React.Key[]`	—	Controlled selected row keys
`defaultSelectedRows`	`React.Key[]`	—	Default selected keys (uncontrolled)
`onSelectionChange`	`(keys, records) => void`	—	Selection change callback
`selectedRowColor`	`MantineColor`	—	Selected row background color
`enableKeyboardNavigation`	`boolean`	`true` when `selectionMode` is set	Enable keyboard nav
`onRowActivate`	`(record, index) => void`	—	Enter key callback
`renderContextMenu`	`(info) => ReactNode`	—	Context menu content (use `Menu.Item`)
`onRowContextMenu`	`(record, index, event) => void`	—	Right-click callback
`hiddenColumns`	`string[]`	—	Controlled hidden column keys
`defaultHiddenColumns`	`string[]`	—	Default hidden columns (uncontrolled)
`onHiddenColumnsChange`	`(keys) => void`	—	Hidden columns change callback
`enableColumnVisibilityToggle`	`boolean`	`false`	Right-click header to toggle columns
`resizeMode`	`'standard' \	'finder'`	`'standard'`
`tableProps`	`Partial<TableProps>`	—	Props passed to inner `<Table>`
`stickyHeader`	`boolean`	`false`	Sticky table header
`stickyHeaderOffset`	`number \	string`	`0`
`tabularNums`	`boolean`	`false`	Tabular number alignment

🎨 New Styles API

New selectors: selectedRow, focusedRow

New CSS variables:

Variable	Description
`--list-view-selected-row-color`	Background color of selected rows
`--list-view-sticky-blur`	Backdrop blur for sticky column overlay

💥 Breaking Changes

[!CAUTION]
This release contains breaking changes. Review the migration guide below before upgrading.

1. Props interface no longer extends `TableProps`

Table-level props (variant, layout, etc.) must now be passed through tableProps:

// Before
<ListViewTable variant="vertical" />

// After
<ListViewTable tableProps={{ variant: 'vertical' }} />

2. `enableColumnReordering` and `enableColumnResizing` default to `false`

Previously both defaulted to true. Now you must opt in:

<ListViewTable enableColumnReordering enableColumnResizing />

3. Component `ref` type changed

// Before
const ref = useRef<HTMLTableElement>(null);

// After
const ref = useRef<HTMLDivElement>(null);

4. Context menu requires `Menu.Item` elements

The renderContextMenu prop must now return Mantine Menu.Item / Menu.Divider components instead of arbitrary JSX:

// Before
renderContextMenu={() => (
  <Stack gap={0}>
    <UnstyledButton>Copy</UnstyledButton>
  </Stack>
)}

// After
renderContextMenu={() => (
  <>
    <Menu.Item leftSection={<IconCopy size={14} />}>Copy</Menu.Item>
  </>
)}

5. `visibleMediaQuery` removed from column config

Use the new hiddenColumns prop instead for programmatic column visibility.

6. `contextMenu` Styles API selector removed

The context menu is now powered by Mantine's Menu, which has its own styling system.

🐛 Bug Fixes

Double-click no longer triggers drag resize — event.detail >= 2 guard prevents mousedown from starting a drag during double-click
Auto-fit preserves table width — adjacent column compensates the exact delta in standard mode
Controlled sort respects external data order — no internal re-sorting when sortStatus + onSort are both provided
Keyboard navigation bounds check — Enter/Space no longer fire with invalid indices after data filtering
Range selection clamped — Shift+click clamps to [0, data.length - 1] when data changes between clicks

🔧 Improvements

Resize handle UX overhaul — 14px hit area (20px touch), animated indicator line with spring curve
Finder-style header focus — inset bottom border instead of background highlight
Accessible focus indicator — :focus-visible outline on root element for keyboard users
Sticky columns without !important — cleaner CSS specificity
Vertical variant — now supports dot-notation keys (getNestedValue) and renderCell

Migration Guide

Step 1: Install the update

yarn add @gfazioli/mantine-list-view-table@^2.0.0

Step 2: Wrap Table props in `tableProps`

If you passed Mantine Table props directly, move them:

// Before
<ListViewTable variant="vertical" layout="fixed" />

// After
<ListViewTable tableProps={{ variant: 'vertical', layout: 'fixed' }} />

Step 3: Opt in to reordering/resizing

<ListViewTable enableColumnReordering enableColumnResizing />

Step 4: Update ref type

const ref = useRef<HTMLDivElement>(null); // was HTMLTableElement

Step 5: Update context menu

Replace custom JSX with Menu.Item from @mantine/core:

import { Menu } from '@mantine/core';

renderContextMenu={({ record }) => (
  <>
    <Menu.Item leftSection={<IconCopy size={14} />}>Copy</Menu.Item>
    <Menu.Divider />
    <Menu.Item color="red" leftSection={<IconTrash size={14} />}>Delete</Menu.Item>
  </>
)}

Step 6: Replace `visibleMediaQuery`

// Before (on column)
{ key: 'size', visibleMediaQuery: '(min-width: 768px)' }

// After (on component)
<ListViewTable hiddenColumns={isMobile ? ['size'] : []} />

Compatibility

Mantine: 8.x
React: 18.x / 19.x
@tabler/icons-react: ^3.34.0
License: MIT

Mantine Rings Progress - A Complete Rewrite Inspired by Apple Watch

Giovambattista Fazioli — Fri, 20 Mar 2026 16:38:58 +0000

The concentric ring progress component for Mantine gets a major upgrade: native RingProgress, glow effects, staggered animations, unified tooltips, and full accessibility — all in one release.

Introduction

Version 3.0.0 of @gfazioli/mantine-rings-progress is a ground-up rewrite. The internal fork of Mantine's RingProgress has been completely removed, replaced by the native component from @mantine/core. This eliminates ~600 lines of custom SVG and animation code while adding 10 new features that bring the component closer to the Apple Watch activity rings experience.

Whether you're building fitness dashboards, goal trackers, or compact data visualizations, this release gives you the tools to make your rings shine — literally.

✨ New Features

Per-ring Customization

Each ring can now override global props individually. Mix thick and thin rings, toggle round caps per ring, or set a custom background track color:

const rings = [
  { value: 40, color: 'cyan', thickness: 18 },
  { value: 65, color: 'red', thickness: 10, roundCaps: false },
  { value: 90, color: '#f90', thickness: 6, rootColor: 'gray' },
];

<RingsProgress size={180} rings={rings} />

Supported per-ring overrides: thickness, roundCaps, rootColor, glowIntensity, glowColor, ariaLabel, tooltip.

Staggered Entrance Animation

Instead of all rings appearing at once, use staggerDelay to animate them one after another — outer ring first, inner ring last:

<RingsProgress animate staggerDelay={300} transitionDuration={1000} rings={rings} />

Glow / Neon Effect

Add a neon-like glow that follows the ring shape using CSS drop-shadow. Set glow={true} for a default 6px blur, or pass a custom radius. Each ring can override the effect with glowIntensity and glowColor:

<RingsProgress glow={8} rings={rings} />

Pulse on Completion

When a ring reaches 100%, trigger a satisfying scale + brightness pulse animation — inspired by the Apple Watch ring closure celebration:

<RingsProgress pulseOnComplete rings={rings} />

The animation respects prefers-reduced-motion and uses a data-pulsing attribute for CSS customization.

`onRingComplete` Callback

Run custom logic when a ring crosses the 100% threshold:

<RingsProgress
  onRingComplete={(index, ring) => {
    showNotification({ message: `${ring.color} ring completed!` });
  }}
  rings={rings}
/>

Start Angle & Direction

Control where rings start filling and in which direction:

<RingsProgress startAngle={90} direction="counterclockwise" rings={rings} />

startAngle={0} is the 12 o'clock position (default). Direction accepts 'clockwise' or 'counterclockwise'.

Unified Tooltip

The new withTooltip prop shows a single, chart-style tooltip with color swatches for all rings — no more overlapping per-ring tooltips:

<RingsProgress
  withTooltip
  rings={[
    { value: 20, color: 'green', tooltip: 'Fitness – 40 Gb' },
    { value: 80, color: 'blue', tooltip: 'Running – 50 min' },
  ]}
/>

If tooltip is not set on a ring, the percentage value is shown automatically.

Accessibility

The component is now fully accessible out of the box:

Root element: role="group" with aria-label="Progress rings" (overridable)
Each ring: role="progressbar" with aria-valuenow, aria-valuemin, aria-valuemax
Per-ring ariaLabel for custom screen reader text
Automatic prefers-reduced-motion support via useReducedMotion

💥 Breaking Changes

This is a major release with breaking changes. Here's what you need to update:

Animation props renamed/removed

  <RingsProgress
-   animationDuration={1000}
-   animationSteps={60}
-   animationTimingFunction="ease"
+   transitionDuration={1000}
    animate
    rings={rings}
  />

animationDuration → transitionDuration (default changed from 1000 to 0)
animationSteps — removed (CSS transitions replaced JS setInterval)
animationTimingFunction — removed (CSS uses ease by default)

Tip: If you only use animate for entrance animation, you can omit transitionDuration entirely — the component auto-applies 1000ms during the entrance phase.

Ring type changed

- import { RingProgressSection } from '@gfazioli/mantine-rings-progress';
- const rings: RingProgressSection[] = [...]
+ import { RingsProgressRing } from '@gfazioli/mantine-rings-progress';
+ const rings: RingsProgressRing[] = [...]

The base properties (value, color, tooltip) remain the same, so existing code that only uses those will work without changes.

Props interface

RingsProgressProps now extends BoxProps + StylesApiProps + ElementProps<'div'> (standard Mantine pattern) instead of the forked RingProgressProps. All common props (size, thickness, roundCaps, label, animate) are still available.

Styles API

A new 'label' style name was added. Style names are now 'root' | 'ring' | 'label'.

🔧 Improvements

Drastically simplified internals

The entire forked RingProgress/ directory (~600 lines) has been deleted. The component now delegates entirely to Mantine's native RingProgress, ensuring better compatibility with future Mantine releases and smaller bundle size.

Smart entrance animation

The component auto-applies 1000ms transition during the entrance phase only. After all rings mount, transitionDuration reverts to 0 — preventing geometry changes (like resizing) from triggering unwanted CSS transitions.

Interactive demos

The documentation now includes replay buttons for animation demos, interactive sliders for the pulse demo, and a configurator with all new props.

🐛 Bug Fixes

Label centering: Fixed the label being offset from center — now rendered as a separate overlay
Debug styles: Removed hardcoded color: 'red' on the label
Theme overrides: Fixed useProps('Rings', ...) → useProps('RingsProgress', ...)
Countdown demo: Added transitionDuration={0} to prevent CSS transitions from interfering with rapid updates

Getting Started

npm install @gfazioli/mantine-rings-progress@3

Import styles at the root of your application:

import '@gfazioli/mantine-rings-progress/styles.css';

Basic usage with the new features:

import { RingsProgress } from '@gfazioli/mantine-rings-progress';

function ActivityRings() {
  const rings = [
    { value: 75, color: 'green', tooltip: 'Move' },
    { value: 50, color: 'blue', tooltip: 'Exercise' },
    { value: 90, color: 'orange', tooltip: 'Stand' },
  ];

  return (
    <RingsProgress
      size={180}
      rings={rings}
      animate
      staggerDelay={300}
      glow={6}
      withTooltip
      pulseOnComplete
      onRingComplete={(i) => console.log(`Ring ${i} done!`)}
    />
  );
}

Mantine Border Animate - A Complete Beam Rewrite with Dual Rendering Modes

Giovambattista Fazioli — Wed, 18 Mar 2026 08:09:00 +0000

The beam variant has been completely rebuilt with two rendering engines, multi-color gradient support, and a streamlined API.

Introduction

Version 1.0.0 of @gfazioli/mantine-border-animate is a major release that reimagines how animated borders work. The beam effect — the heart of the component — now ships with two distinct rendering modes, letting you choose between pixel-perfect border tracing and smooth conic rotation. Combined with new multi-color gradients, hover pause, custom easing, and built-in accessibility, this release makes animated borders more flexible, more beautiful, and easier to use than ever.

What's New

Two Beam Rendering Modes

The biggest addition in v1.0 is the beamMode prop, which lets you choose how the beam effect is rendered:

Path mode (beamMode="path", the new default) uses CSS offset-path to move a radial-gradient circle along the component's border. The beam maintains a uniform size at every position and travels at constant speed along the perimeter. This is the best choice for most UI elements.

<BorderAnimate beamMode="path" size="md" duration={5}>
  <Card>Your content</Card>
</BorderAnimate>

Conic mode (beamMode="conic") uses a rotating conic-gradient wedge animated via CSS @property. The rotation is buttery smooth, and the size prop controls the angular spread of the wedge (from a tight 18-degree spotlight at xs to a full 180-degree sweep at xl). It works best on circular or near-square elements.

<BorderAnimate beamMode="conic" size="lg" duration={3}>
  <Avatar radius="100%" />
</BorderAnimate>

Multi-Color Gradients with `colorStops`

Move beyond two-color gradients. The new colorStops prop gives you full control over the beam's colors:

<BorderAnimate
  colorStops={[
    { color: 'transparent', position: 0 },
    { color: 'green', position: 20 },
    { color: 'cyan', position: 40 },
    { color: 'yellow', position: 60 },
    { color: 'red', position: 80 },
    { color: 'transparent', position: 100 },
  ]}
>
  <Paper>Multi-color beam</Paper>
</BorderAnimate>

colorStops works with both beam modes:

Path mode generates a radial-gradient with concentric color rings
Conic mode generates a custom conic-gradient — use transparent stops for beam/wedge effects, or fill the entire circle for a rotating rainbow border

Pause on Hover

Interactive elements often need the animation to pause during user interaction. The new pauseOnHover prop does exactly that — using pure CSS animation-play-state with zero JavaScript overhead:

<BorderAnimate pauseOnHover>
  <Button>Hover me to pause</Button>
</BorderAnimate>

Custom Timing Functions

Fine-tune animation feel with timingFunction. By default, beam uses linear and glow/pulse use ease-in-out, but you can override with any CSS timing function:

<BorderAnimate timingFunction="ease-in-out" />
<BorderAnimate timingFunction="cubic-bezier(0.4, 0, 0.2, 1)" />
<BorderAnimate timingFunction="steps(8)" />  {/* retro pixel effect */}

Accessibility Out of the Box

BorderAnimate now respects prefers-reduced-motion automatically. Users who have enabled "Reduce motion" in their OS settings will see no animations — no configuration needed, no extra props. It just works.

Breaking Changes

This is a major release with several breaking changes. Here's what you need to update:

`gradient` variant removed

The gradient variant is gone. Use beamMode="conic" with full colorStops instead:

// v0.x
<BorderAnimate variant="gradient" colorFrom="red" colorTo="blue" />

// v1.0
<BorderAnimate
  beamMode="conic"
  colorStops={[
    { color: 'red', position: 0 },
    { color: 'blue', position: 50 },
    { color: 'red', position: 100 },
  ]}
/>

`opacity` renamed to `borderOpacity`

The old opacity prop conflicted with the CSS opacity property inherited from Mantine's BoxProps. It's now borderOpacity:

// v0.x
<BorderAnimate opacity={0.5} />

// v1.0
<BorderAnimate borderOpacity={0.5} />

`anchor` and `count` props removed

Both props have been removed with no direct replacement. Simply remove them from your components.

`size` semantics changed

The size prop now behaves differently depending on beamMode:

Path mode: still pixel-based (xs=64px to xl=480px) — same as v0.x
Conic mode: angular spread of the wedge (xs=18 degrees to xl=180 degrees)

`BorderAnimateVariant` type updated

Improvements

Glow z-index fix — the glow variant now correctly renders behind content, preventing the overlay from obscuring text
Accurate demos — all documentation demos now show code that exactly matches the rendered output
New exported types — BorderAnimateBeamMode, BorderAnimateColorStop, and BorderAnimateVariant are now properly exported for consumers

Getting Started

Install or update:

npm install @gfazioli/mantine-border-animate@1

Import styles at the root of your application:

import '@gfazioli/mantine-border-animate/styles.css';

Basic usage:

import { BorderAnimate } from '@gfazioli/mantine-border-animate';

function Demo() {
  return (
    <BorderAnimate>
      <Paper withBorder p="md" radius="md">
        Your content with an animated border
      </Paper>
    </BorderAnimate>
  );
}

Mantine QR Code - A Real QR Code Generator for Mantine

Giovambattista Fazioli — Tue, 17 Mar 2026 15:35:35 +0000

Generate fully scannable, beautifully styled QR codes with custom dot shapes, finder patterns, image overlays, and one-click SVG/PNG download — all integrated with the Mantine design system.

Introduction

The Mantine QR Code component has been completely rebuilt from the ground up. What was previously an LED-style indicator has been transformed into a fully functional QR code generator that produces real, scannable codes from any string input. It renders pure SVG for crisp output at any resolution, follows Mantine's Styles API conventions, and ships with a dedicated download hook for exporting to SVG, PNG, JPEG, or WebP.

✨ New Features

Real QR Code Generation

The component now encodes actual QR code data using the qrcode library. Pass any string — a URL, WiFi credentials, vCard, plain text — and get a scannable QR code rendered as optimized SVG.

import { QRCode } from '@gfazioli/mantine-qr-code';

function Demo() {
  return <QRCode value="https://mantine.dev" />;
}

The value prop is the only required prop. Everything else has sensible defaults.

Dot Styles

Control the appearance of data modules with the dotStyle prop. Three built-in styles are available:

<QRCode value="https://mantine.dev" dotStyle="square" />   {/* Default */}
<QRCode value="https://mantine.dev" dotStyle="rounded" />
<QRCode value="https://mantine.dev" dotStyle="dots" />

Each style generates a single combined <path> element for all data modules, keeping the DOM lightweight even for dense QR codes.

Corner Styles

The three finder patterns (the large squares in the corners) can be styled independently with cornerStyle:

<QRCode value="https://mantine.dev" cornerStyle="square" />   {/* Default */}
<QRCode value="https://mantine.dev" cornerStyle="rounded" />
<QRCode value="https://mantine.dev" cornerStyle="dots" />

Mix and match dot and corner styles for unique designs:

<QRCode
  value="https://mantine.dev"
  dotStyle="dots"
  cornerStyle="rounded"
  color="violet"
/>

Image Overlay with Excavation

Add a logo or image at the center of the QR code. The component automatically removes ("excavates") the data modules behind the image to keep the code scannable:

<QRCode
  value="https://mantine.dev"
  size="xl"
  image="https://example.com/logo.png"
  imageSize={0.2}
  imageRadius="md"
  imagePadding={1}
  imageExcavate={true}
  errorCorrectionLevel="H"
/>

Tip: Use errorCorrectionLevel="H" when overlaying images — it provides 30% error correction, ensuring the code remains scannable even with a portion covered.

Error Correction Levels

Four standard error correction levels are supported via the errorCorrectionLevel prop:

Level	Recovery	Best for
`L`	~7%	Dense data, minimal damage expected
`M`	~15%	General use (default)
`Q`	~25%	Moderate resilience
`H`	~30%	Image overlays, printed codes

`useQRCodeDownload` Hook

A dedicated hook makes it easy to export the QR code in multiple formats:

import { QRCode, useQRCodeDownload } from '@gfazioli/mantine-qr-code';

function Demo() {
  const { ref, download, getDataUrl } = useQRCodeDownload({
    fileName: 'my-qr-code',
    scale: 4,          // 4x resolution for raster formats
  });

  return (
    <>
      <QRCode ref={ref} value="https://mantine.dev" />
      <button onClick={() => download({ format: 'svg' })}>Download SVG</button>
      <button onClick={() => download({ format: 'png' })}>Download PNG</button>
    </>
  );
}

Supported formats: svg, png, jpeg, webp. The getDataUrl function returns a data URL — useful for preview thumbnails or embedding.

Theme-Aware Colors

Both foreground and background colors integrate with the Mantine theme:

<QRCode value="https://mantine.dev" color="blue" background="gray.1" />
<QRCode value="https://mantine.dev" color="white" background="dark" />
<QRCode value="https://mantine.dev" color="teal" background="transparent" />

Full Styles API

The component exposes 8 style selectors for granular customization:

Selector	Element	Description
`root`	`<div>`	Outer container
`svg`	`<svg>`	SVG element
`background`	`<rect>`	Background rectangle
`modules`	`<path>`	Combined data modules path
`finderPattern`	`<g>`	Finder pattern group (×3)
`finderOuter`	`<path>`	Outer ring of finder pattern
`finderInner`	`<path>`	Inner square of finder pattern
`image`	`<image>`	Center image overlay

CSS Variables

Variable	Description
`--qr-code-size`	Width and height
`--qr-code-radius`	Container border radius
`--qr-code-color`	Foreground (module) color
`--qr-code-background`	Background color

Size presets: xs (80px), sm (120px), md (160px), lg (200px), xl (256px).

🔧 Improvements

SVG Accessibility: The SVG element includes role="img" and an aria-label derived from the encoded value.
Optimized Rendering: All data modules are combined into a single <path> element, keeping the DOM minimal regardless of QR code density.
Memoized Computation: QR matrix generation and SVG path building are wrapped in useMemo — re-computation only happens when relevant props change.
SSR Compatible: No browser-only APIs (window, document) are used during rendering. The download hook uses browser APIs only when explicitly called.

📖 Complete Props Reference

interface QRCodeBaseProps {
  value: string;                              // Required — data to encode
  size?: MantineSize | string | number;       // Default: 'md'
  radius?: MantineRadius | string | number;   // Container border radius
  color?: MantineColor;                       // Default: 'dark'
  background?: MantineColor | 'transparent';  // Default: 'white'
  errorCorrectionLevel?: 'L' | 'M' | 'Q' | 'H'; // Default: 'M'
  quietZone?: number;                         // Default: 1
  dotStyle?: 'square' | 'rounded' | 'dots';  // Default: 'square'
  cornerStyle?: 'square' | 'rounded' | 'dots'; // Default: 'square'
  image?: string;                             // Center image URL
  imageSize?: number;                         // 0–1, default: 0.2
  imageRadius?: MantineRadius | string | number;
  imagePadding?: number;                      // Default: 1
  imageExcavate?: boolean;                    // Default: true
}

Getting Started

Install the package:

npm install @gfazioli/mantine-qr-code

Import styles at the root of your application:

import '@gfazioli/mantine-qr-code/styles.css';

Use the component:

import { QRCode } from '@gfazioli/mantine-qr-code';

function App() {
  return (
    <QRCode
      value="https://mantine.dev"
      size="lg"
      dotStyle="rounded"
      cornerStyle="rounded"
      color="blue"
    />
  );
}

Use Cases

{/* URL */}
<QRCode value="https://mantine.dev" />

{/* WiFi credentials */}
<QRCode value="WIFI:T:WPA;S:MyNetwork;P:MyPassword;;" />

{/* vCard contact */}
<QRCode value="BEGIN:VCARD\nVERSION:3.0\nFN:John Doe\nTEL:+1234567890\nEND:VCARD" />

Mantine Scene - Cinematic Backgrounds for Your React Apps

Giovambattista Fazioli — Sun, 15 Mar 2026 13:22:00 +0000

Layer gradients, glowing blobs, star fields, auroras, and more into rich, composable decorative backgrounds — all powered by Mantine.

Introduction

Mantine Scene is a brand-new composable background component for React that lets you build atmospheric, animated backgrounds by stacking visual layers. Think of it as a stage director for your UI — you compose the mood by combining gradients, glow effects, dot grids, star fields, snowfall, auroras, and more, all with first-class Mantine theme integration, responsive props, and accessibility baked in from day one.

This 1.0.0 release ships with 10 composable sub-components, full interactive mouse-tracking support, GPU-accelerated animations, and a complete documentation site with live configurators for every layer type.

What's New in 1.0.0

The Scene Component

The root Scene component acts as a container for all visual layers. It supports fullscreen mode, interactive mouse tracking, and respects prefers-reduced-motion out of the box.

import { Scene } from '@gfazioli/mantine-scene';

function HeroBackground() {
  return (
    <Scene fullscreen interactive>
      <Scene.Gradient from="violet" to="transparent" animate />
      <Scene.Glow color="blue" size={300} />
      <Scene.StarField count={80} twinkle />
      <Scene.Noise opacity={0.03} />
    </Scene>
  );
}

Root Props:

Prop	Type	Default	Description
`fullscreen`	`boolean`	`false`	Cover the entire viewport with `position: fixed`
`interactive`	`boolean`	`false`	Enable mouse tracking for compatible sub-components
`interactiveEasing`	`number`	`0.12`	Smoothness of cursor tracking (0–1)
`reducedMotion`	`'auto' \	'always' \	'never'`
`zIndex`	`number`	`0`	z-index in fullscreen mode

10 Composable Sub-Components

Every sub-component is a visual layer you can freely compose. Layer order follows DOM order — the last child renders on top.

✨ Scene.Gradient

Radial, linear, or conic gradients with optional rotate or pulse animation. Supports interactive mouse tracking for radial/conic types.

<Scene.Gradient
  type="radial"
  from="violet"
  to="transparent"
  fromOpacity={0.2}
  animate
  animationType="rotate"
  duration={20}
/>

✨ Scene.Glow

Floating, animated glow blobs. Choose between float, pulse, or breathe animation styles. Supports responsive size and blur props and interactive mouse tracking.

<Scene.Glow
  color="cyan"
  size={{ base: 200, md: 400 }}
  blur={{ base: 80, md: 120 }}
  opacity={0.5}
  animate
  animationType="float"
  driftX="30px"
  driftY="20px"
/>

✨ Scene.DotGrid

Repeating dot patterns with optional stagger (honeycomb) layout, fade masks, and twinkle animation. Supports responsive spacing.

<Scene.DotGrid
  color="gray"
  spacing={{ base: 16, md: 24 }}
  stagger
  fade="radial"
  animate
/>

✨ Scene.Mesh

Multi-stop radial gradient overlay simulating a mesh gradient. Supports hue-rotate animation and blend modes.

<Scene.Mesh
  stops={[
    { color: 'violet', position: '20% 30%', spread: 50 },
    { color: 'pink', position: '80% 20%', spread: 40 },
    { color: 'blue', position: '50% 80%', spread: 60 },
  ]}
  animate
  blend="screen"
/>

✨ Scene.Noise

SVG-based film grain texture. Add subtle texture to any background with configurable grain, seed, and color tint.

<Scene.Noise opacity={0.03} grain={0.65} type="fractalNoise" tint="blue" />

✨ Scene.StarField

CSS-only star field with deterministic PRNG positioning and twinkle animation across 3 staggered layers. Supports responsive count.

<Scene.StarField count={{ base: 50, md: 100 }} twinkle duration={3} seed={42} />

✨ Scene.StarWarp

Hyperspace warp-speed effect with configurable focal point, direction, and streak trails. Supports responsive count and interactive mouse tracking for the focal point.

<Scene.StarWarp
  count={100}
  speed={1.5}
  direction="out"
  trail
  color="white"
/>

✨ Scene.ShootingStar

Animated shooting star trails at configurable angles and intervals. Multiple lanes with randomized timing for a natural feel.

<Scene.ShootingStar
  count={3}
  angle={215}
  trailLength={80}
  speed={1}
  minInterval={3}
  maxInterval={8}
/>

✨ Scene.Snow

Falling snowflakes with horizontal drift and wind control. Supports responsive count for performance-conscious responsive designs.

<Scene.Snow
  count={{ base: 30, md: 50 }}
  speed={1}
  drift={30}
  wind={0.2}
/>

✨ Scene.Aurora

Shimmering aurora borealis bands with wave animation. Configurable band count, position, and colors.

<Scene.Aurora
  colors={['green', 'teal', 'cyan']}
  bands={3}
  position="top"
  opacity={0.3}
  blur={60}
/>

Key Features

🎨 Full Mantine Theme Integration

Every color prop accepts MantineColor values, so your backgrounds stay consistent with your theme. Shade overrides are available on components like Glow and DotGrid.

📱 Responsive Props

Key numeric props support Mantine's responsive object syntax. This means you can adjust visual density based on breakpoint — fewer stars on mobile, larger glows on desktop:

<Scene.StarField count={{ base: 40, sm: 60, md: 100 }} />
<Scene.Glow size={{ base: 150, md: 400 }} blur={{ base: 60, md: 120 }} />

Responsive props are available on: Glow (size, blur), DotGrid (spacing), StarField (count), StarWarp (count), Snow (count).

🖱️ Interactive Mouse Tracking

Set interactive on the root Scene to enable cursor-driven effects:

Glow — blob position follows the mouse
Gradient — radial/conic center follows the mouse
StarWarp — focal point tracks the mouse

The interactiveEasing prop controls how smoothly elements follow the cursor (0 = sluggish, 1 = instant). Components gracefully fall back to their default positions when the mouse leaves.

♿ Accessibility

The root component renders with aria-hidden="true" — it's purely decorative
reducedMotion="auto" respects prefers-reduced-motion by default
Set reducedMotion="always" to disable all animations, or "never" to force them on

⚡ Performance

All animations use GPU-accelerated CSS (transform, opacity) — no JavaScript animation loops
Deterministic PRNG (seeded) for StarField, StarWarp, ShootingStar, and Snow ensures reproducible layouts without runtime randomness
StarWarp caps at 200 elements; Snow recommends ~80 max for smooth performance
Responsive count props let you reduce particle counts on lower-powered devices

🎛️ Styles API

Full Mantine Styles API support. Override styles for any part of any sub-component using classNames, styles, or unstyled props. CSS variables are exposed for all dynamic values (e.g., --scene-glow-size, --scene-aurora-duration).

Putting It All Together

Here's a complete example combining multiple layers into a rich hero background:

import { Scene } from '@gfazioli/mantine-scene';

function CosmicHero() {
  return (
    <Scene fullscreen interactive interactiveEasing={0.08}>
      {/* Base gradient */}
      <Scene.Gradient type="radial" from="indigo" fromOpacity={0.2} animate />

      {/* Mesh overlay */}
      <Scene.Mesh
        stops={[
          { color: 'violet', position: '25% 25%' },
          { color: 'blue', position: '75% 75%' },
        ]}
        blend="screen"
        opacity={0.6}
      />

      {/* Floating glows */}
      <Scene.Glow color="cyan" size={350} top="20%" left="30%" />
      <Scene.Glow color="violet" size={250} top="60%" left="70%" delay={2} />

      {/* Stars */}
      <Scene.StarField count={{ base: 60, md: 120 }} twinkle />
      <Scene.ShootingStar count={2} />

      {/* Subtle texture */}
      <Scene.Noise opacity={0.02} />
    </Scene>
  );
}

Getting Started

Installation

npm install @gfazioli/mantine-scene
# or
yarn add @gfazioli/mantine-scene

Import Styles

Add the styles import to your app entry point:

import '@gfazioli/mantine-scene/styles.css';

Or use the @layer variant for CSS cascade control:

import '@gfazioli/mantine-scene/styles.layer.css';

Requirements

React 18 or 19
@mantine/core >= 7.0.0
@mantine/hooks >= 7.0.0