Universal Asset

A lightweight, modular Flutter package for displaying different types of assets (images, SVGs, Lottie animations, Rive animations) using a single widget with automatic type detection and graceful fallback handling.

Features

🎯 Single Widget: Use UniversalAsset for all asset types
🚀 Automatic Detection: File type detection based on extensions and MIME types
📦 Modular Dependencies: Optional imports - only add what you need
🛡️ Graceful Degradation: Fallback widgets when dependencies are missing
🎨 Highly Customizable: Extensive configuration options for each asset type
🔍 Error Handling: Comprehensive error handling with debugging support
♿ Accessibility: Full semantic support for screen readers
💾 Memory Support: Load assets from memory (Uint8List)

Supported Asset Types

Type	Extensions	Package Required	Features
Images	`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp`	None (Flutter built-in)	Placeholder, error handling, color filters
SVG	`.svg`	`flutter_svg`	Color override, theme adaptation, color filters
Lottie	`.json`	`lottie`	Speed control, repeat, reverse, custom controllers
Rive	`.riv`	`rive`	Artboard selection, state machines, animations
Network Images	Any image URL	`cached_network_image` (optional)	Caching, headers, timeout configuration
Memory	`Uint8List`	None	Direct memory rendering

Installation

Add universal_asset to your pubspec.yaml:

dependencies:
  universal_asset: ^1.0.1

Optional Dependencies

Add only the packages you need:

dependencies:
  # For SVG support
  flutter_svg: ^2.0.9

  # For Lottie animations
  lottie: ^3.0.0

  # For Rive animations
  rive: ^0.12.0

  # For cached network images
  cached_network_image: ^3.3.0

Basic Usage

import 'package:universal_asset/universal_asset.dart';

// Automatic type detection
UniversalAsset('assets/logo.png')
UniversalAsset('assets/icon.svg')
UniversalAsset('assets/animation.json')  // Lottie
UniversalAsset('assets/character.riv')   // Rive
UniversalAsset('https://example.com/image.png')

// From memory
UniversalAsset.memory(uint8ListData)

// With sizing
UniversalAsset(
  'assets/logo.png',
  width: 200,
  height: 100,
  fit: BoxFit.cover,
)

Advanced Configuration

Lottie Animations

UniversalAsset(
  'assets/loading.json',
  lottieConfig: LottieConfig(
    speed: 1.5,
    repeat: true,
    reverse: false,
    onLoaded: () => print('Lottie loaded!'),
  ),
)

Rive Animations

UniversalAsset(
  'assets/character.riv',
  riveConfig: RiveConfig(
    artboard: 'MainArtboard',
    stateMachine: 'StateMachine',
    autoplay: true,
    onInit: () => print('Rive initialized!'),
  ),
)

SVG Customization

UniversalAsset(
  'assets/icon.svg',
  svgConfig: SvgConfig(
    colorOverride: Colors.blue,
    adaptToTheme: true,
    colorFilter: ColorFilter.mode(Colors.red, BlendMode.srcIn),
  ),
)

Network Images

UniversalAsset(
  'https://example.com/image.jpg',
  networkConfig: NetworkImageConfig(
    useCache: true,
    headers: {'Authorization': 'Bearer token'},
    timeout: Duration(seconds: 30),
  ),
  placeholder: CircularProgressIndicator(),
  errorWidget: Icon(Icons.error),
)

Error Handling

When a required package is missing, UniversalAsset shows a helpful error widget:

// If flutter_svg is not installed
UniversalAsset('assets/icon.svg')
// Shows: "SVG support not available. Add flutter_svg to pubspec.yaml"

Custom Error Widgets

UniversalAsset(
  'invalid/path.png',
  errorWidget: Container(
    child: Text('Custom Error Message'),
  ),
)

Complete Example

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

class AssetGallery extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Universal Asset Demo')),
      body: Column(
        children: [
          // Standard image
          UniversalAsset(
            'assets/photo.jpg',
            width: 200,
            height: 150,
            fit: BoxFit.cover,
          ),

          // SVG with color override
          UniversalAsset(
            'assets/icon.svg',
            width: 48,
            height: 48,
            svgConfig: SvgConfig(
              colorOverride: Theme.of(context).primaryColor,
            ),
          ),

          // Lottie animation
          UniversalAsset(
            'assets/loading.json',
            width: 100,
            height: 100,
            lottieConfig: LottieConfig(
              repeat: true,
              speed: 1.2,
            ),
          ),

          // Network image with caching
          UniversalAsset(
            'https://picsum.photos/200/200',
            width: 200,
            height: 200,
            networkConfig: NetworkImageConfig(
              useCache: true,
            ),
            placeholder: CircularProgressIndicator(),
          ),
        ],
      ),
    );
  }
}

API Reference

UniversalAsset

Parameter	Type	Description
`source`	`String?`	Asset path or URL
`memory`	`Uint8List?`	Memory data (alternative to source)
`width`	`double?`	Asset width
`height`	`double?`	Asset height
`fit`	`BoxFit?`	How asset fits within bounds
`alignment`	`AlignmentGeometry`	Asset alignment (default: center)
`colorFilter`	`ColorFilter?`	Color filter to apply
`placeholder`	`Widget?`	Loading placeholder
`errorWidget`	`Widget?`	Error fallback widget
`mimeType`	`String?`	MIME type hint for detection
`lottieConfig`	`LottieConfig?`	Lottie-specific configuration
`riveConfig`	`RiveConfig?`	Rive-specific configuration
`svgConfig`	`SvgConfig?`	SVG-specific configuration
`networkConfig`	`NetworkImageConfig?`	Network image configuration
`semanticLabel`	`String?`	Accessibility label
`excludeFromSemantics`	`bool`	Exclude from accessibility tree

Testing

Run tests with:

flutter test

The package includes comprehensive tests for:

Asset type detection
Widget rendering
Error handling
Configuration options

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Development Setup

Clone the repository
Run flutter pub get

Add optional dependencies for testing:

flutter pub add --dev flutter_svg lottie rive cached_network_image

Run tests: flutter test
Run the example app: cd example && flutter run

Roadmap

Video asset support
GIF animation controls
3D model support (glTF)
PDF rendering support
Custom asset type plugins
Performance optimizations
Web-specific optimizations

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

📖 Documentation
🐛 Issue Tracker

Made with ❤️ for the Flutter community