Skip to main content

Documentation Index

Fetch the complete documentation index at: https://synapsync.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
NbxNetworkImage

A robust network image widget that provides comprehensive image loading, caching, error handling, and customization options.

​
Basic Usage

import 'package:nebux_design_system/nebux_design_system.dart';

NbxNetworkImage(
  imageUrl: 'https://example.com/image.jpg',
  width: 200,
  height: 200,
)

​
Core Properties

​
imageUrl
String
required
The URL of the image to load and display
​
width
double?
The width of the image. If null, sizes based on content
​
height
double?
The height of the image. If null, sizes based on content
​
fit
BoxFit
default:"BoxFit.cover"
How to inscribe the image into the space
​
placeholder
Widget?
Widget displayed while the image is loading
​
errorWidget
Widget?
Widget displayed when an error occurs loading the image
​
httpHeaders
Map<String, String>?
HTTP headers to use when loading the image

​
Configuration Options

NbxNetworkImage uses four configuration classes:

​
NbxImageCacheConfig

Controls image caching behavior:
​
memCacheWidth
int?
Maximum width for in-memory cache
​
memCacheHeight
int?
Maximum height for in-memory cache
​
maxWidthDiskCache
int?
Maximum width for disk cache
​
maxHeightDiskCache
int?
Maximum height for disk cache
​
cacheKey
String?
Custom cache key (defaults to image URL)
​
useOldImageOnUrlChange
bool
default:"false"
Whether to keep displaying old image when URL changes
​
cacheManager
BaseCacheManager?
Custom cache manager instance
NbxNetworkImage(
  imageUrl: 'https://example.com/large-image.jpg',
  cacheConfig: NbxImageCacheConfig(
    memCacheWidth: 800,
    memCacheHeight: 800,
    maxWidthDiskCache: 1200,
    maxHeightDiskCache: 1200,
  ),
)

​
NbxImageAnimationConfig

Controls fade animations:
​
fadeInDuration
Duration
default:"Duration(milliseconds: 500)"
Duration of fade-in animation
​
fadeOutDuration
Duration
default:"Duration(milliseconds: 300)"
Duration of fade-out animation
​
fadeInCurve
Curve
default:"Curves.easeIn"
Curve for fade-in animation
​
fadeOutCurve
Curve
default:"Curves.easeOut"
Curve for fade-out animation
NbxNetworkImage(
  imageUrl: 'https://example.com/image.jpg',
  animationConfig: NbxImageAnimationConfig(
    fadeInDuration: Duration(milliseconds: 800),
    fadeInCurve: Curves.easeInOut,
  ),
)

​
NbxImageProgressConfig

Customizes the loading progress indicator:
​
progressIndicatorBuilder
Widget Function(BuildContext, String, DownloadProgress)?
Custom builder for progress indicator
​
progressIndicatorCircular
bool
default:"true"
Whether to use circular (true) or linear (false) progress indicator
​
progressIndicatorSize
Size
default:"Size(40, 40)"
Size of the progress indicator
​
progressIndicatorStrokeWidth
double
default:"3.0"
Stroke width for circular progress indicator
​
progressIndicatorColor
Color?
Color of the progress indicator
​
progressIndicatorBackgroundColor
Color?
Background color of the progress indicator
NbxNetworkImage(
  imageUrl: 'https://example.com/image.jpg',
  progressConfig: NbxImageProgressConfig(
    progressIndicatorCircular: true,
    progressIndicatorColor: Colors.blue,
    progressIndicatorSize: Size(50, 50),
  ),
)

​
NbxImageStyleConfig

Controls visual styling:
​
borderRadius
BorderRadius?
Border radius applied to the image container
​
border
BoxBorder?
Border drawn around the image container
​
shadow
List<BoxShadow>?
Box shadows applied to the image container
​
clipBehavior
Clip
default:"Clip.antiAlias"
Clip behavior for the image container
​
color
Color?
Color filter applied to the image
​
colorBlendMode
BlendMode?
Blend mode for the color filter
​
filterQuality
FilterQuality
default:"FilterQuality.low"
Filter quality for image rendering
​
repeat
ImageRepeat
default:"ImageRepeat.noRepeat"
How the image should repeat if it doesn’t fill its bounds
​
matchTextDirection
bool
default:"false"
Whether to match the text direction for the image
NbxNetworkImage(
  imageUrl: 'https://example.com/image.jpg',
  styleConfig: NbxImageStyleConfig(
    borderRadius: BorderRadius.circular(12),
    border: Border.all(color: Colors.grey, width: 2),
    shadow: [
      BoxShadow(
        color: Colors.black26,
        blurRadius: 8,
        offset: Offset(0, 4),
      ),
    ],
  ),
)

​
Convenience Constructors

NbxNetworkImage provides factory constructors for common use cases:

​
Circular Image

NbxNetworkImageExtensions.circular(
  imageUrl: 'https://example.com/avatar.jpg',
  radius: 50,
  border: Border.all(color: Colors.white, width: 3),
)

​
Square Image

NbxNetworkImageExtensions.square(
  imageUrl: 'https://example.com/thumbnail.jpg',
  size: 100,
  borderRadius: BorderRadius.circular(8),
)

​
Rounded Image

NbxNetworkImageExtensions.rounded(
  imageUrl: 'https://example.com/photo.jpg',
  width: 300,
  height: 200,
  borderRadius: 16,
)

​
Advanced Examples

​
Profile Avatar

NbxNetworkImageExtensions.circular(
  imageUrl: user.avatarUrl,
  radius: 40,
  placeholder: Container(
    width: 80,
    height: 80,
    decoration: BoxDecoration(
      shape: BoxShape.circle,
      color: Colors.grey[300],
    ),
    child: Icon(Icons.person, size: 40, color: Colors.grey[600]),
  ),
  errorWidget: Container(
    width: 80,
    height: 80,
    decoration: BoxDecoration(
      shape: BoxShape.circle,
      color: Colors.red[100],
    ),
    child: Icon(Icons.error, size: 40, color: Colors.red),
  ),
)

​
Image with Custom Loading

NbxNetworkImage(
  imageUrl: 'https://example.com/image.jpg',
  width: 300,
  height: 200,
  progressConfig: NbxImageProgressConfig(
    progressIndicatorBuilder: (context, url, progress) {
      return Container(
        color: Colors.grey[200],
        child: Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              CircularProgressIndicator(
                value: progress.progress,
              ),
              SizedBox(height: 8),
              Text(
                '${((progress.progress ?? 0) * 100).toInt()}%',
                style: TextStyle(color: Colors.grey[600]),
              ),
            ],
          ),
        ),
      );
    },
  ),
)

​
Image Grid

GridView.builder(
  gridDelegate: SliverGridDelegateWithFixedCrossAxisCount(
    crossAxisCount: 3,
    crossAxisSpacing: 8,
    mainAxisSpacing: 8,
  ),
  itemCount: images.length,
  itemBuilder: (context, index) {
    return NbxNetworkImageExtensions.square(
      imageUrl: images[index],
      size: 120,
      borderRadius: BorderRadius.circular(8),
    );
  },
)

​
Header Image with Overlay

Stack(
  children: [
    NbxNetworkImage(
      imageUrl: 'https://example.com/header.jpg',
      width: double.infinity,
      height: 250,
      fit: BoxFit.cover,
      styleConfig: NbxImageStyleConfig(
        color: Colors.black.withOpacity(0.3),
        colorBlendMode: BlendMode.darken,
      ),
    ),
    Positioned(
      bottom: 16,
      left: 16,
      child: Text(
        'Title',
        style: TextStyle(
          color: Colors.white,
          fontSize: 24,
          fontWeight: FontWeight.bold,
        ),
      ),
    ),
  ],
)

​
Best Practices

Use memCacheWidth and memCacheHeight to reduce memory usage for large images by caching a scaled-down version.
The component uses cached_network_image package internally, providing automatic disk and memory caching.
When displaying multiple images in a list, consider setting appropriate cache dimensions to optimize memory usage.
The default filterQuality is set to low for better performance. Increase to medium or high if image quality is critical.