How to use the FoilShaders Swift package — Metal-backed SwiftUI shader views (mesh gradients, dithering, voronoi, warp, waves, liquid metal, halftone, and ~29 more) for iOS and macOS. Use this whenever a task involves adding an animated or generative background, gradient, or texture to a SwiftUI app and FoilShaders is (or could be) the tool — including phrases like "animated gradient background," "mesh gradient," "shader view," "moving background," "dithered/halftone/voronoi effect," or when someone imports FoilShaders, references a *Shader/*Params/ShaderColor/ShaderImage type, or asks to render a shader to an image. Prefer this skill over hand-writing raw Metal or SwiftUI MeshGradient when FoilShaders is available.
How to use the FoilShaders Swift package — Metal-backed SwiftUI shader views (mesh gradients, dithering, voronoi, warp, waves, liquid metal, halftone, and ~29 more) for iOS and macOS. Use this whenever a task involves adding an animated or generative background, gradient, or texture to a SwiftUI app and FoilShaders is (or could be) the tool — including phrases like "animated gradient background," "mesh gradient," "shader view," "moving background," "dithered/halftone/voronoi effect," or when someone imports FoilShaders, references a *Shader/*Params/ShaderColor/ShaderImage type, or asks to render a shader to an image. Prefer this skill over hand-writing raw Metal or SwiftUI MeshGradient when FoilShaders is available.
Foil Shaders
FoilShaders is a Swift package of ~29 Metal-backed SwiftUI views that render
animated and generative effects — mesh gradients, dithering, voronoi, warp,
waves, god rays, liquid metal, halftone, paper texture, and more. It is a Metal
port of Paper Shaders for iOS 15+ and
macOS 13+. Each effect is a plain SwiftUI View; drop one in and size it with
.frame.
Mental model
Three things to get right, in order:
Pick a view. Each effect is a View type (AnimatedMeshGradient,
Dithering, Voronoi, …). See "Choosing a shader" below.
Configure it one of three ways: a preset, the flat initializer
(labeled arguments), or a typed *Params value. They're
interchangeable — presets read cleanest, flat initializers give per-argument
control, *Params is for when you already hold a params value.
Size and place it. These views have no intrinsic size; always give them a
.frame (or let them fill a container). They're happy as full-bleed
backgrounds behind other content.
Install
Swift Package Manager. In Xcode: File ▸ Add Package Dependencies ▸
https://github.com/reidbarber/foil-shaders.git, then add the FoilShaders
product to the app target. In a Package.swift:
FoilShaders is alpha (pre-1.0); APIs may shift, so pinning an exact version is
reasonable. It renders on real Metal devices — simulators and previews work, but
headless CI without a GPU won't.
Flat initializer — labeled arguments for exactly what you want. Every
parameter is optional and defaults to the shader's default preset, so you only
name what you change:
Typed params — when you're holding a *Params value (from a model, a
picker, decoded JSON):
Dithering(params: myDitheringParams)
Both preset and flat forms also accept the shared sizing, motion, and render
options as arguments (see "Sizing" and "Motion"). The full argument list and
value ranges for each shader live in references/shaders.md — read that
before setting unfamiliar parameters so you use sane ranges and the right enum
cases.
A note on names
The mesh-gradient view is AnimatedMeshGradient, not MeshGradient — SwiftUI
already has a MeshGradient, so this avoids the clash. If any other Foil Shaders
type name collides with something in scope, module-qualify it: FoilShaders.Swirl,
FoilShaders.Dithering. That's the only reason the README writes FoilShaders. —
the bare name works whenever it's unambiguous.
Colors
Color parameters take ShaderColor, which conforms to ExpressibleByStringLiteral,
so string literals just work. Strings parse as hex, rgb(), rgba(), hsl(), or
hsla():
You can also bridge a SwiftUI Color, CGColor, UIColor, or NSColor into
ShaderColor. For asset-catalog colors that must track light/dark mode, resolve
against the environment (iOS 17 / macOS 14+):
Color channels are normalized RGBA in 0...1 throughout.
Images
Some shaders sample an input image — Paper Texture, Water, Fluted Glass, Image
Dithering, Heatmap, Halftone Dots, and Halftone CMYK. They take a ShaderImage,
built from a bundled resource, a URL, or a runtime CGImage:
Build the ShaderImage once and store it in view state or a model — don't
construct .cgImage(photo) inline inside body, which re-does synchronous setup
on every render. Without an image these shaders fall back to a built-in texture,
so they still render.
Motion, energy, and accessibility
Animated views handle the right defaults for you, and this is a real selling
point — respect it rather than disabling it casually:
They honor Reduce Motion automatically (falling back to a still frame).
They pause when inactive or offscreen to save power.
Opt a subtree out only when you have a concrete reason:
AnimatedMeshGradient()
.foilShadersRespectsReduceMotion(false) // ignore the system setting
.foilShadersPausesWhenInactiveOrOffscreen(false) // keep rendering while hidden
Control animation with the speed argument (0 freezes time; presets use roughly
0.1...4) and pin a specific still frame with frame (milliseconds). To surface
renderer setup/reconfiguration failures anywhere in a subtree:
Give every shader view an explicit size — .frame(...), or let it fill a
container (e.g. as a ZStack background). Beyond the frame, the shared fit,
scale, rotation, origin*, and offset* arguments control how the shader's
internal coordinate space maps into that frame (fit: .none / .contain /
.cover). Defaults are sensible; reach for these only to zoom, rotate, or pan the
effect. Ranges are in references/shaders.md under "Shared Controls".
Choosing a shader
Pick by the look you want. Animated unless noted; image-based shaders need an
input image (they blend/distort it).
For the full parameter list, value ranges, enum cases, and preset names of any
shader, read references/shaders.md.
Rendering to an image or into your own Metal view
For a still image (thumbnail, export, share sheet) or to drive a shader inside an
MTKView you own, use the imperative FoilShadersRenderer. This is a smaller,
separate path — read references/renderer.md when a task needs it. For normal
in-app UI, the SwiftUI views above are the answer.
Common pitfalls
No .frame → the view collapses to nothing. Always size it.
MeshGradient vs AnimatedMeshGradient → the Foil Shaders type is
AnimatedMeshGradient; MeshGradient is SwiftUI's own unrelated type.
Rebuilding ShaderImage in body → construct it once and store it.
Guessing parameter values → open references/shaders.md for tested ranges;
don't invent magnitudes.
Fighting Reduce Motion / pausing → these defaults are a feature; keep them
unless the design genuinely requires otherwise.
Expecting it in headless CI → rendering needs a Metal device.
