ColorfulX Documentation

repository·main·Indexed 19 days ago

A Metal-backed gradient renderer for iOS, macOS, tvOS, and visionOS. It features LAB color interpolation and spring-based animation for high-performance multicolor backgrounds. Provides SwiftUI components like ColorfulView and MulticolorGradient, as well as UIKit and AppKit support via AnimatedMulticolorGradientView and MulticolorGradientView.

Tokens: 2.3K
Snippets: 6
Records: 8
Agent score: 17%

What's inside ColorfulX

Create custom palettes with ColorfulColors

main

You can define your own repeatable color palettes by conforming an enum or type to the ColorfulColors protocol. This allows your custom themes to be used seamlessly with both ColorfulView (SwiftUI) and setColors (UIKit/AppKit).

enum MarketingTheme: ColorfulColors {
    case hero

    var colors: [ColorElement] {
        [
            make(227, 108, 155),
            make(134, 90, 214),
            make(73, 204, 236),
            make(35, 219, 167)
        ]
    }
}

// Usage in SwiftUI
ColorfulView(color: MarketingTheme.hero)

// Usage in UIKit
animatedView.setColors(MarketingTheme.hero)

Install ColorfulX via Swift Package Manager
main
Add ColorfulX to your project dependencies using Swift Package Manager.
Dependency URL: https://github.com/Lakr233/ColorfulX.git
Minimum Version: 5.8.0
Steps:
1. Add the package URL to your dependencies.
2. Add ColorfulX to your target dependencies in Package.swift or via Xcode's File → Add Packages… menu.
```
.package(url: "https://github.com/Lakr233/ColorfulX.git", from: "5.8.0")

// In your target
.target(
    name: "MyApp",
    dependencies: ["ColorfulX"]
)
```
https://github.com/lakr233/colorfulx/blob/main/README.md
Troubleshoot ColorfulX issues
main
Common issues and solutions:
- No animation appearance: Verify speed > 0 and ensure the view is currently attached to a window (it pauses when detached).
- Palette updates snap instantly: Ensure you pass animated: true (the default) and that transitionSpeed is greater than zero when calling setColors.
- Visible aliasing: Increase renderScale toward 1.0 or higher, especially when using high noise values.
- Fewer than expected colors: Ensure repeats is true or provide at least as many colors as needed (maximum of eight).
https://github.com/lakr233/colorfulx/blob/main/README.md

Use ColorfulView in SwiftUI for animated gradients

main

The ColorfulView is the primary SwiftUI component for driving time-based, animated multicolor gradients. It supports bindings to ColorfulPreset, [Color], or any custom type conforming to ColorfulColors.

Key features:

Animation Control: Use speed, bias, noise, and transitionSpeed to shape the movement.
Performance: Control frameLimit (rendering frequency) and renderScale (Metal drawable scale) to optimize for battery or resolution.
Custom Directors: Use the animationDirector parameter to change movement patterns (e.g., SpeckleAnimationRoundedRectangleDirector).

import ColorfulX
import SwiftUI

struct AnimatedGradientDemo: View {
    @State private var preset: ColorfulPreset = .aurora
    @State private var speed: Double = 1.0
    @State private var bias: Double = 0.01
    @State private var noise: Double = 8.0
    @State private var transition: Double = 3.5
    @State private var frameLimit: Int = 60
    @State private var renderScale: Double = 1.0

    var body: some View {
        ColorfulView(
            color: $preset,
            speed: $speed,
            bias: $bias,
            noise: $noise,
            transitionSpeed: $transition,
            frameLimit: $frameLimit,
            renderScale: $renderScale
        )
        .ignoresSafeArea()
    }
}

Use MulticolorGradientView in UIKit & AppKit

main

For static gradients in UIKit or AppKit, use MulticolorGradientView and assign a Parameters object to its parameters property.

import ColorfulX
import ColorVector

let staticView = MulticolorGradientView()
staticView.parameters = .init(
    points: [
        .init(color: ColorVector(UIColor.systemOrange, usingSpace: .lab), position: .init(x: 0.0, y: 0.0)),
        .init(color: ColorVector(UIColor.systemTeal, usingSpace: .lab), position: .init(x: 1.0, y: 0.5)),
        .init(color: ColorVector(UIColor.systemPurple, usingSpace: .lab), position: .init(x: 0.2, y: 1.0))
    ],
    bias: 0.015,
    power: 4,
    noise: 0
)

Use MulticolorGradient in SwiftUI for static gradients

main

For non-animated backgrounds, use the MulticolorGradient wrapper. This uses MulticolorGradientView under the hood and requires a MulticolorGradientView.Parameters object defining the color stops and their positions.

Note: The underlying shader supports up to eight color stops. If you provide fewer, the view can repeat stops to fill the pipeline.

import ColorfulX
import SwiftUI
import ColorVector

struct StaticGradientDemo: View {
    private let parameters = MulticolorGradientView.Parameters(
        points: [
            .init(
                color: ColorVector(UIColor.systemPink, usingSpace: .lab),
                position: .init(x: 0.0, y: 0.0)
            ),
            .init(
                color: ColorVector(UIColor.systemBlue, usingSpace: .lab),
                position: .init(x: 1.0, y: 1.0)
            )
        ],
        bias: 0.01,
        power: 4,
        noise: 0
    )

    var body: some View {
        MulticolorGradient(parameters: parameters)
            .ignoresSafeArea()
    }
}

Use AnimatedMulticolorGradientView in UIKit & AppKit
main
To use animated gradients in imperative frameworks, instantiate AnimatedMulticolorGradientView and configure its properties directly.
Use setColors(_:animated:repeats:) to update the palette.
- animated: true (default) enables smooth interpolation via transitionSpeed.
- repeats: true (default) fills unused color slots (up to 8) by repeating colors.
```
import ColorfulX

let animatedView = AnimatedMulticolorGradientView()
animatedView.setColors(ColorfulPreset.aurora)
animatedView.speed = 1.2
animatedView.bias = 0.01
animatedView.noise = 12
animatedView.transitionSpeed = 4.0
animatedView.frameLimit = 60
animatedView.renderScale = 1.0
```
https://github.com/lakr233/colorfulx/blob/main/README.md

Reference: ColorfulX Parameters

main

Configuration parameters for controlling the visual behavior and performance of the gradients.

Parameter	Applies To	Description
`speed`	Animated views	Scales how quickly speckles traverse the canvas.
`bias`	Animated & static	Controls gradient spread. Lower values harden the shape. Typical range: `0.00001 ... 0.01`.
`power`	Static	Shapes the falloff curve (default is `4`).
`noise`	Animated & static	Adds procedural noise; higher values increase GPU cost.
`transitionSpeed`	Animated views	Determines how fast colors interpolate when palettes change.
`frameLimit`	Animated views	Caps rendering frequency. Use `0` for unlimited.
`renderScale`	Animated & static	Adjusts Metal drawable scale. Lowering improves performance.
`repeats`	Animated views	Fills unused color slots by repeating colors.