visual_effects_kit 0.1.1

Procedural Flutter visual effects for animated backgrounds, surfaces, and interactive UI accents.

visual_effects_kit

visual_effects_kit is a publishable Flutter package for procedural, animated visual effects that fill any rectangular widget, clipped surface, or background layer with smooth motion and optional pointer interaction.

It is designed for modern Flutter UIs on web, desktop, and mobile, with a clean registry-driven architecture that lets you select effects by effectName or effectIndex and register your own effects later.

Features

• Reusable VisualEffectSurface widget for backgrounds and shaped surfaces
• Built-in effect registry with lookup by string name or integer index
• Three included effects: plusGrid, dotField, and waveGrid
• Premium hover response on web and desktop, with touch-friendly fallback on mobile
• Strongly typed immutable VisualEffectConfig with copyWith
• Clean custom effect API for future package or app-specific extensions
• Lightweight v1 implementation using only Flutter primitives

Installation

Add the package to your pubspec.yaml:

dependencies:
  visual_effects_kit: ^0.1.0

Then fetch packages:

flutter pub get

Quick start

import 'package:flutter/material.dart';
import 'package:visual_effects_kit/visual_effects_kit.dart';

class HeroBackground extends StatelessWidget {
  const HeroBackground({super.key});

  @override
  Widget build(BuildContext context) {
    return VisualEffectSurface(
      effectName: 'plusGrid',
      config: const VisualEffectConfig(
        backgroundColor: Color(0xFF08111E),
        foregroundColor: Color(0xFFD8E7FF),
        accentColor: Color(0xFF7AF3E0),
        density: 1.2,
        maxScale: 2.4,
        interactionRadius: 150,
      ),
      child: const Center(
        child: Text(
          'Interactive Background',
          style: TextStyle(color: Colors.white, fontSize: 28),
        ),
      ),
    );
  }
}

Selecting effects

Use either the effect name or effect index:

VisualEffectSurface(effectName: 'dotField');
VisualEffectSurface(effectIndex: 2);

Resolution rules:

• If effectName is provided, it wins
• Otherwise effectIndex is used
• Otherwise the first registered effect is used

Registry helpers:

final names = VisualEffects.effectNames;
final count = VisualEffects.effectCount;
final effects = VisualEffects.availableEffects;

Built-in effects

• plusGrid: A responsive grid of symbols such as "+" that smoothly scales near the pointer
• dotField: A softly animated field of dots with hover-reactive emphasis
• waveGrid: A subtle grid of moving capsules with wave motion and optional pointer disturbance

Configuration

VisualEffectConfig keeps the public API small and practical while still covering the most useful controls:

const config = VisualEffectConfig(
  backgroundColor: Color(0xFF0A1220),
  foregroundColor: Color(0xFFD7E3F7),
  accentColor: Color(0xFF77F2D7),
  density: 1.1,
  symbol: '+',
  baseCellSize: 28,
  minScale: 0.9,
  maxScale: 2.5,
  interactionRadius: 140,
  animationSpeed: 1.0,
  opacity: 1.0,
  padding: EdgeInsets.all(12),
  randomSeed: 7,
);

Adding custom effects

You can register your own effects globally:

class MyEffect extends VisualEffect {
  const MyEffect();

  @override
  String get name => 'myEffect';

  @override
  String get displayName => 'My Effect';

  @override
  String get description => 'An app-specific effect.';

  @override
  void paint(
    Canvas canvas,
    VisualEffectConfig config,
    VisualEffectFrame frame,
    VisualEffectDrawingContext context,
  ) {
    // Custom drawing here.
  }
}

void registerEffects() {
  VisualEffects.register(const MyEffect());
}

Example app

The package includes a polished /example app that demonstrates:

• switching effects by name and by index
• live controls for density, radius, scale, speed, opacity, symbol, and palettes
• an overlay panel above the animated background
• a clear hover-focused plusGrid demo for Flutter web and desktop

Run it locally:

cd example
flutter run -d chrome

Publishing readiness

This package includes:

• package metadata suitable for pub.dev
• a license file
• changelog
• analysis options
• package tests
• example app
• DartDoc comments on the public API

Before publishing, you may still want to add repository and issue tracker links in pubspec.yaml if you have them.

Roadmap

• optional shader-backed effects for high-end surfaces
• layered compositing and blend modes
• effect presets and theme packs
• mask-aware and shape-aware effect adapters
• image and particle-driven hybrid effects