NiriFX

Explode windows into fragments. Slide them into ribbons. Make them wobble.

NiriFX brings customizable animations to the niri Wayland compositor. Pick a finished style from 80 presets, 9 effect families and 16 ready-made profiles. For further customization, tune it in Studio, online or on your desktop. Use different effects for opening and closing, from a quiet ripple to a full window explosion.

Works standalone or with iNiR/iRiS, DankMaterialShell and Noctalia. Quickshell is optional. Studio opens as an app-style window or a browser tab.

Interactive gallery · Web Studio · All presets & comparisons · Preset reference · Documentation · Roadmap · Changelog

Opening, closing and resize effects work on stock Niri, tested with 26.04. Built-in presets leave resize unchanged. The NiriFX session adds movement and swaps, pointer deformation, continuous fragments and interruption improvements in one compositor build. Choose which effects to use in Library; you do not need to choose individual patches.

The complete session is included in the niri-fx and niri-fx-git Arch packages, with a source-build workflow for other setups. Stock Niri remains available, and NiriFX does not patch your shell's source files.

This README describes main, which can include features newer than the latest release. Download v0.22.2 for the versioned package, or read choosing a version. NiriFX is in 0.x development. See the path to 1.0 for planned stability guarantees and acceptance criteria.

New in development: try continuous fragment dragging directly in Studio, with native-checked motion for Gentle, Tear and Cascade. Local Studio also offers reviewed setup and updates from an installed complete package. What's changed · Upgrade a released installation.

Quick start

Try without installing: choose from nine starter looks, open Web Studio, or choose Try in Studio from the gallery. Choose a ready-made combo in Library, share one style across selected actions or mix opening and closing styles. Click Preview combo to watch the whole sequence. Choose Preserve / NiriFX Style / Off independently for each action. Preserve uses your underlying Niri or shell configuration, including customizations. Save a named profile, share its settings or download JSON. Previewing does not change your desktop. Bring a downloaded style to Niri.

Arch Linux / CachyOS: install niri-fx from AUR, then run niri-fx studio --active. The Arch guide covers release and niri-fx-git packages, updates and existing managed sessions. Starting with 0.22, either package includes Studio, CLI, presets and the complete NiriFX session. Keep using stock Niri with the tools, or set up the included session.

For a small install without the source gallery, use the release wheel. On Niri with Python 3.10+, you can also open Library from source:

git clone --depth 1 https://github.com/jturbide/niri-fx.git
cd niri-fx
python3 -m niri_fx studio

Choose a recommended combo, set each action to Preserve / NiriFX Style / Off, then choose Review & apply. Review the proposed changes before clicking Apply these changes. Restore previous returns to your previous settings. Use the same Library workflow with plain Niri or a supported shell; setup guides explain each connection. If several shells coexist, choose the target explicitly as shown in those guides.

Both sessions can share your normal Niri settings and the same effect choices; stock Niri uses its supported actions.

For the full NiriFX session, follow session setup, then open python3 -m niri_fx studio --target native. Choose presets for each action and review Apply to desktop when the running build matches, or Select for next login. Shared setups use Apply shared settings to update the files both sessions follow. Updated NiriFX builds let you choose different Move and Swap styles. Swap targets explicit left/right window swaps; dragging and column reordering use Move. The build and acceptance matrix explains what is tested and what still needs physical desktop validation.

Prefer the terminal? Run python3 -m niri_fx to choose a preset, review its files and type apply. Run it again and choose undo to restore. No extra UI toolkit is required. Terminal guide.

Browse by look with python3 -m niri_fx list --collections --text, then try python3 -m niri_fx list --collection shapes --text. The same ten collections appear in Studio and the gallery.

For a direct connection to your Niri configuration, run python3 -m niri_fx studio --target standalone. Previewing changes no active animations. For scriptable setup on plain Niri:

python3 -m niri_fx setup --target standalone --preset balanced
python3 -m niri_fx setup --target standalone --preset balanced --apply

Already using a shell's animation picker? Follow its guide: iNiR / iRiS · DMS · Noctalia · Standalone / Waybar. The scenario guide helps choose the right setup and restore path.

Using an AI agent? Start with python3 -m niri_fx agent-info for structured command discovery, or read the agent guide. The CLI provides compact preset search, parameter bounds, validated exports and reviewed Apply/Restore. A reusable skill is included in version 0.18 and newer.

See it in motion

The interactive gallery starts with nine recommended looks, with Fragments first. Choose Open/close pairings for finished combinations or All examples to explore the whole collection. Search, family/scenario filters and click-to-play previews help narrow it down. It starts paused and loads one animation at a time. Style cards link to editable settings, JSON downloads and a local Studio command. Share a filtered view or a customized Studio link. The full catalog includes every preset, control comparison and downloadable example.

Fragments first

Fragments preserve pieces of the window's texture and reconstruct them in their original places. Start with Balanced, use Explosion for a stronger burst, or Implosion for an inward collapse.

Balanced	Explosion	Implosion
Core Detonation	Mosaic Burst	Orbital Ribbons

Tune particle density, gravity, spin, release order, waves, size variation and burst origin. Compare those controls. These clips use Studio's real shaders with synthetic window content.

Continuous fragment dragging

Choose Gentle, Tear or Cascade for Move, then grab the sample window in development Studio. Hold, pause, reverse direction and release: nearby pieces follow first while distant pieces wait, catch up and reconstruct.

Gentle	Tear	Cascade

These are browser previews using native response and mesh math with synthetic input, not desktop recordings. Use the NiriFX session for real window dragging. Response settings and limits · Importable recipes

More fragment shapes

Triangle Shatter, Circle Burst, Rectangle Confetti and Hex Swarm combine new geometry with the existing gravity and spin controls. Studio also supports ellipses, diamonds and stars, with adjustable proportions, orientation and silhouette timing. Available since v0.12.0; existing resize settings are preserved.

Triangle Shatter	Circle Burst
Rectangle Confetti	Hex Swarm

Shape controls and comparisons · Try Triangle Shatter

The NiriFX session also uses these shapes for native movement and swaps:

Triangle swap	Hexagon swap

Mixed fragment shapes

Choose Mixed Confetti for tumbling squares and triangles, or Orbiting Shapes for circles and hexagons. Tune the second shape, mixture and stable layout seed.

Mixed Confetti	Orbiting Shapes

Shape mixtures and settings · Controlled comparison

Coordinated action sets

Choose Fragments Motion, Ribbons Motion or Elastic Motion for matching opening, closing and desktop timing. Studio suggests a companion when you view Resize or Movement; choose the companion to include it in your profile.

Fragments Motion	Ribbons Motion	Elastic Motion
Edge rebuild	Ribbon resize	Spring resize
Fragment swap	Ribbon swap	Elastic swap

The first two rows use real shaders with synthetic content. Swaps are native nested-compositor recordings and require the NiriFX session. Build a combo from an action set · Browse coordinated sets

Coordinated desktop motion

Gentle, Balanced and Playful pair window effects with stock workspace, camera and overview springs.

Gentle	Balanced	Playful

Try a motion pack · Browse desktop profiles

Finished pairings

Choose a coordinated opening and closing look by name; detailed tuning is optional.

Geometric Flow	Ribbon Current	Soft Landing

Browse all sixteen profiles · Choose by collection

Slices, springs and hexagons

Alternating Blinds	Spring Wobble	Hexagon Burst
Ribbon Fold	Twist Snap	Hive Collapse

Pointer-driven wobble

Grab a window, change direction and let it settle. The NiriFX session includes actual drag response. Studio's timed Elastic effects remain a separate choice. Choose Pointer wobble in Library to save a preset or tune its strength, damping and frequency. Use Try pointer wobble to drag the sample window, or Play drag demo for a repeatable comparison. Preview combo includes dragging when pointer strength is above zero. These browser previews use native spring and shader math with synthetic input; they work online without changing your desktop. Portable JSON retains the choice on every setup. Live activation requires a verified running NiriFX compositor; managed session choices are reviewed for the next login.

Gentle	Rubber Sheet	Release Settle

These recordings use real pointer events and synthetic windows in nested Niri. Choose a pointer preset.

These complete Studio combos pair Fragment Flow with each drag preset. Import the portable examples to try them online or in version 0.18 and newer. The source archive includes the examples.

Gentle Fragments	Rubber Sheet Fragments	Release Settle Fragments

Pixels, ink and distortion

Pixel Wipe	Ink Spread	Signal Glitch
Frost Vanish	Ink Bloom	Chromatic Glitch

Also explore dust, wisps, iris reveals and shockwaves. Ember Erosion and Signal Glitch start monochrome; their colors are configurable. Original NiriFX shaders are inspired by the wider desktop-effects community.

Vortex distortion

Vortex Fold curls the window into its center; Soft Swirl gives it a quicker, gentler counterclockwise turn. Change twist direction, contraction, falloff and origin in Studio. Available since v0.11.0.

Vortex Fold	Soft Swirl

Compare spin directions · Controls and settings

Pick an opening and closing pair

Choose a finished combination with no JSON editing. In the terminal guide, type profiles; in Studio, start with Library and Preview combo. The desktop pickers include the same collection. Existing resize settings are preserved.

The five recommended combos balance arrival and departure timing. Resize and movement stay off until selected. These clips show the complete shader cycle with synthetic window content.

Fragment Flow	Geometric Flow	Soft Landing
Ribbon Current	Playful Motion	Burst and Drift

python3 -m niri_fx list --profiles --text
python3 -m niri_fx studio --profile fragment-flow

All 16 profiles, commands and downloads · Ghost and Shockwave

Resize

Choose fragment breakup, Elastic Stretch, Accordion Resize, Ripple Resize, Edge Ripple or Torsion Resize. These work on stock Niri's animated size changes, such as cycling column widths. They do not add pointer-driven wobble while dragging an edge.

Resize guide · Elastic profile · Accordion profile · Ripple profile

Edge Ripple and Torsion Resize each offer Subtle and Expressive profiles since v0.11.0. Compare both strengths below, then download a profile from the resize guide.

Edge Ripple	Torsion Resize

Movement and swaps

The NiriFX session includes movement and swap effects. These recordings use an isolated compositor and synthetic app cards. Stock Niri stays installed alongside the NiriFX session.

Fragment explosion	Slice Exchange
Pixel Transfer	Soft Phase

Repeated swaps preserve the current deformation and seed, with blended direction changes. Closing during an opening continues its original trajectory while fading out. Closing during movement retains the movement state instead of creating a new particle field.

Redirect a moving window	Close during opening

Eight quick direction changes, carrying the wobble through each retarget:

Run the nested demo · Movement behavior and limits · All native swaps and interruption recordings

The windows still render independently; particles do not share collision physics or one combined depth order. Studio now previews the actual movement shader on a synthetic directional path; its older Move/Swap sketches remain labelled concepts.

Movement beyond horizontal swaps

Fragment Wake, Ribbon Transfer and Momentum Glide provide three movement looks. The patched compositor also handles vertical reorder and consume/expel animation paths. The pointer extension adds drag response; custom workspace effects remain on the roadmap.

Fragment Wake	Ribbon Transfer	Momentum Glide

Controls, profile export and isolated demos

Smoother resize reversals

The 0.19 compositor patches keep neighboring edges aligned in the resize reversals below. These native comparisons show the 0.18 baseline beside the updated geometry, using plain synthetic cards.

Width reversal	Height reversal

Behavior, requirements and limits

The NiriFX 0.20 session also maintains spacing between neighboring windows when an extreme resize reaches the minimum size:

Minimum width	Minimum height

Resize effects that continue through retargets

The NiriFX 0.20 session preserves an active NiriFX resize effect when another size change arrives. Pieces keep their layout and deformation phase; new window content blends into that continuing animation.

Fragments	Triangles

These are native recordings at their configured speed. Build the NiriFX session and generate the resize shader from the same checkout to try it. Stock Niri keeps its existing resize behavior. Closing during resize still uses a snapshot on older builds. Retained resize appearance and limits.

Keep resizing while closing

The NiriFX 0.20 session carries a running resize through closing. The current pieces keep their phase and size trajectory while fading out, with borders and shadows following the changing window.

This native comparison uses the same triangle effect and timings on both sides. The handoff takes precedence over the ordinary close style during an active resize. Requirements and tested limits.

Shaped resize

Use triangles, hexagons and other fragment shapes during resize with these ready-made profiles.

Triangle Edge Rebuild	Hexagon Edge Rebuild	Circle Soft Reflow

Importable profiles and resize controls

Make it yours

Open niri-fx studio, choose Open, Close, Resize, Move or Swap, and click a style to see it play. Mix different styles or choose a complete look from Combos. Review and apply directly from Studio. In a matching NiriFX session, effects update immediately; Customize your combo and the editor hold detailed tuning.

Keep your existing opening, choose a closing style and turn resize off:

Preserve restores the underlying configuration for that action. It can include custom Niri or shell settings. Action choices and examples.

The installed app provides reviewed Apply and Restore previous through standalone, iNiR/iRiS or connected Noctalia configuration. The same library works in Web Studio for previews and JSON/config downloads. Library and shell setup. My profiles keeps saved combos together, with copy, rename and remove controls. Saving over a name asks you to replace that Library copy; active effects change only through Review & apply.

Studio offers a Basic / Advanced control view, search and favorites, independent action profiles, Undo/Redo and pinned A/B comparisons. Preview combo plays opening, a pause, selected resize/movement loops, optional pointer drag and release, then closing using each action's style and timing. Pause or scrub individual action previews; Reduced Motion shows endpoints without playback and respects the system preference. Preview preferences do not change exported effects.

Import one of the JSON examples, edit it and export a preset or Niri config. Studio guide · Profiles · Control reference.

Desktop pickers

Prefer your terminal? niri-fx provides preset search, reviewed Apply and Undo without a graphical toolkit. Guided workflow:

Run python3 -m niri_fx picker from the checkout to browse styles and load JSON profiles. Review the affected files before Apply; Undo restores the previous settings. Custom resize effects require explicit consent. Choose a toolkit:

Toolkit	Command from a checkout	Integration guide
Quickshell	python3 -m niri_fx picker	Reusable QML picker
GTK 4 / GJS	python3 -m niri_fx picker --toolkit gtk	Standalone GTK and AGS 3 example

Both provide reusable components for custom settings pages.

Only the chosen UI's toolkit is needed; the GTK picker also works without AGS. Studio and standalone setup remain independent of both toolkits. Available since v0.9.0; built-in open/close pairings require v0.10.0.

Performance and compatibility

Effect cost depends on the renderer, window size and settings. The performance guide includes reproducible shader benchmarks; the validation record describes native tests and remaining hardware limits. Particle count is a visual control, not a universal quality setting. The fragment optimization results compare shader costs while keeping the same particles and motion.

Feature	Requirement
Open/close, nine families	Stock Niri with animations enabled
Resize, four families	Stock Niri; choose a profile action or a style with --resize
Movement, swaps, pointer wobble, continuous fragments and interruption continuity	Full NiriFX session
iNiR/iRiS, DMS, Noctalia pickers	Optional shell integrations
Waybar or another bar on Niri	Standalone path; no effects plugin needed

Built with and connected to

Built for niri with Python, GLSL and WebGL. Shell adapters share the same effect catalog and CLI. Explore the related projects, integration roadmap and brand assets.

Help and contributing

Open an issue with your Niri version, effect settings and steps to reproduce a problem. Remove personal information from logs and recordings. See security reporting for vulnerabilities.

Ask questions, share setups and discuss ideas in Discussions. Contributions are welcome: presets, documentation, hardware results and code. Contributing explains the checks and review process; ROADMAP.md describes the next priorities.

License

Original code, shaders and sample artwork are MIT licensed. The optional Niri patches and derived browser pointer preview use GPL-3.0-or-later, with their license. See third-party notices. NiriFX is independent and is not affiliated with Niri, iNiR, DMS or Noctalia.

Support NiriFX

If NiriFX makes your desktop more enjoyable, you can support its development through GitHub Sponsors. Bug reports, shared presets, documentation and hardware testing also help.

Star history