FxImage

FxImage is a versatile image primitive powered by the Hybrid Image Engine. It supports network, asset, local file, and memory sources, along with chainable visual filters like blur and grayscale.

The Hybrid Engine

The FxImage engine can handle file:// and memory:// sources natively. This allows you to capture a photo via Fx.platform.camera and view it instantly with zero extra code.

1. Unified Primitive (`Fx.img`)

The fastest way to display any image source is using the Fx.img() shorthand.

// Network
Fx.img("https://example.com/photo.png").size(100).rounded(20);

// File (Local Storage)
Fx.img("file:///path/to/my/photo.jpg").size(100);

// Memory (Base64 or Bytes)
Fx.img("memory://raw_bytes_here").size(100);

2. Direct Memory Rendering

For pixel-perfect rendering from byte data, use Fx.memoryImage():

Uint8List bytes = await getMyBytes();
Fx.memoryImage(bytes).size(300);

Styling & Filters

Chain filters directly on the style object.

FxImage(
  "assets/photo.jpg",
  style: FxStyle(
    width: 250,
    height: 250,
    imageBlur: 5.0, // Gaussian Blur (sigma 5)
    grayscale: true, // Convert to B&W
    borderRadius: Fx.radius.lg,
  ),
)

Loading & Error Fallback

Provide custom widgets for network loading states or use the built-in shimmers.

FxImage(
  imageUrl,
  style: FxStyle(
    loading: Fx.loader.shimmer(width: 200, height: 200),
    error: Icon(Icons.broken_image, color: Fx.error),
  ),
)

Responsive Images (`Fx.responsiveImage`)

Serve different images based on screen width for performance.

Fx.responsiveImage(
  xs: "mobile-banner.jpg",
  md: "tablet-banner.jpg",
  lg: "desktop-huge.jpg",
  height: 300,
  fit: BoxFit.cover,
)

The Master Image Implementation

Building a high-performance, interactive gallery item with loading shimmers, error recovery, and hover filtering.

class GalleryItem extends StatelessWidget {
  final String imageUrl;

  GalleryItem({required this.imageUrl});

  @override
  Widget build(BuildContext context) {
    final isHovered = flux(false);

    return Fx.box(
      child: Fx(() => Fx.img(imageUrl)
        .w(double.infinity)
        .h(300)
        .fit(BoxFit.cover)
        .loading(Fx.loader.shimmer(height: 300)) // Native shimmer
        .error(Fx.col(
            main: MainAxisAlignment.center,
            children: [
                Icon(Icons.image_not_supported, size: 40, color: Colors.grey),
                Fx.text("Failed to load").muted().mt(8),
            ],
        ))
        .animate(
          blur: isHovered.value ? 5.0 : 0.0,
          grayscale: isHovered.value ? 1 : 0,
          duration: 400.ms,
        )
      )
    )
    .rounded(24)
    .clip() // Ensures image doesn't bleed out of rounded corners
    .onHover((v) => isHovered.value = v)
    .onTap(() => Fx.toast.info("Image Selected"))
    .animate(
        scale: isHovered.value ? 1.05 : 1.0,
        duration: 300.ms,
    );
  }
}

Fluxy's image engine is designed for speed and reliability, ensuring that even complex visual effects like real-time bluring and scaling do not drop frames on lower-end devices.

FxImage

On this page