Animations
@gtkx/animated adapts React Spring to GTKX. Learn how to create and control springs in the React Spring docs; this guide covers how those values reach native GTKX elements. Install the package separately:
npm install @gtkx/animated@1.6.0Animated components
animated(Component) wraps a GTKX element so its mutable props accept values from React Spring. Create the wrapper at module scope, then pass it the values a hook returns:
import { animated, useSpring } from "@gtkx/animated";
import { GtkLabel } from "@gtkx/jsx/gtk";
const AnimatedLabel = animated(GtkLabel);
export const FadeIn = () => {
const styles = useSpring({ from: { opacity: 0 }, to: { opacity: 1 } });
return <AnimatedLabel opacity={styles.opacity} label="Hello" />;
};Keeping the wrapper at module scope gives React a stable component type, so it does not remount between renders.
Property access such as animated.GtkLabel remains available in GTKX 1.6 for compatibility, but is deprecated and removed in 2.0. Import the component and use the call form above. It works for elements that are not widgets, such as GtkAdjustment, and components of your own, while letting a production bundle retain only the components it reaches.
For writable GObject props, each frame updates the native object through its ref without rerendering the component. This includes opacity, margins, size requests, and adjustment values. The style prop, labels, and text children also accept animated values:
const { count } = useSpring({ from: { count: 0 }, to: { count: 100 } });
<AnimatedLabel label={count.to((value) => `${Math.round(value)}%`)} />;GTKX truncates whole-number properties, such as margins, toward zero and clamps values to the native property range. An opacity spring cannot exceed 1, and margins cannot be negative. To slide a widget using a margin, animate from a positive margin to zero.
A custom component that forwards its ref to the native object receives the same updates. Otherwise, the wrapper rerenders the component with the current values.
Props that are not GObject properties, such as the accessible* props, still animate: the component re-renders with the current value on each frame. style updates its CSS provider without rerendering.
Animated styles
In GTKX 1.6, the style prop compiles to a rule in a widget-specific Gtk.CssProvider. The spring reloads that rule each frame without a React render. Use it for effects exposed through CSS, such as color:
import { animated, useSpring } from "@gtkx/animated";
import { GtkLabel } from "@gtkx/jsx/gtk";
const AnimatedLabel = animated(GtkLabel);
export const Deadline = ({ isOverdue }: { isOverdue: boolean }) => {
const { level } = useSpring({ level: isOverdue ? 1 : 0 });
return (
<AnimatedLabel
label="Due today"
style={level.to((value) => ({ color: `mix(var(--window-fg-color), var(--error-color), ${value})` }))}
/>
);
};The interpolation turns a number into a CSS declaration. GTK's mix() blends two colors; alpha() scales a color's opacity.
A spring can also sit on a single declaration rather than on the whole prop, which is how React Spring is written for the DOM:
const styles = useSpring({ from: { color: "red" }, to: { color: "blue" } });
<AnimatedLabel style={styles} label="Due today" />;
<AnimatedLabel style={{ color: styles.color, paddingTop: 4 }} label="Due today" />;Nested blocks also accept springs, such as style={{ "&:hover": { color: styles.color } }}. Only style tracks nested springs; other object-valued props do not.
This also supports effects such as border-radius, box-shadow, and filter.
Moving widgets
To animate position, use a container that exposes it. Inside a GtkFixed, the transform of a GtkFixedLayoutChild is a Gsk.Transform, and an interpolation builds one from the spring:
import { animated, useSpring } from "@gtkx/animated";
import * as Graphene from "@gtkx/gi/graphene";
import * as Gsk from "@gtkx/gi/gsk";
import { GtkButton, GtkFixed, GtkFixedLayoutChild } from "@gtkx/jsx/gtk";
const AnimatedFixedLayoutChild = animated(GtkFixedLayoutChild);
const translate = (x: number): Gsk.Transform | null => Gsk.Transform.new().translate(new Graphene.Point({ x, y: 0 }));
export const Slide = ({ isOpen }: { isOpen: boolean }) => {
const { x } = useSpring({ x: isOpen ? 240 : 0 });
return (
<GtkFixed>
<AnimatedFixedLayoutChild transform={x.to(translate)}>
<GtkButton label="Slide" />
</AnimatedFixedLayoutChild>
</GtkFixed>
);
};Elsewhere, animate the margins, the size requests, a Gtk.Paned's position, or a CSS transform through style, which changes the painted position without changing layout.
React Spring APIs
@gtkx/animated re-exports React Spring's platform-neutral APIs. Use the React Spring documentation to choose and configure hooks, transitions, and controllers, then pass their animated values to GTKX props as shown above. Browser hooks that depend on the DOM have no GTK counterpart and are not exported.
The frame clock
Frames advance during the update phase of a mapped window's GTK frame clock, before layout and painting. GTKX keeps using that window while it can supply frames, switching to another mapped window or a timer when necessary.
Reduced motion
GTK exposes two settings with different effects:
gtk-enable-animationsdisables motion across the toolkit. When false, GTKX springs jump to their targets while still running their lifecycle callbacks.gtk-interface-reduced-motion, available in GTK 4.22 and later, asks applications to reduce motion. It also drives GTK'sprefers-reduced-motionmedia query. Springs keep running; the component chooses an alternative, such as a fade instead of a slide.
useReducedMotion() returns true when either preference calls for less motion, false otherwise, and null before a display is open. It updates when the settings change.
@gtkx/testing disables animations by default, so springs reach their targets on the first frame. Assert the result with findBy* or waitFor. Pass areAnimationsEnabled: true to render when the test needs to exercise motion.
Next
Continue with Cairo to draw 2D graphics inside a widget.