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.

​
Overview

NbxNetworkImage is a comprehensive network image widget that wraps CachedNetworkImage and provides extensive customization for loading, caching, error handling, animations, and styling.

​
Basic Usage

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

​
Widget Properties

​
Required Properties

​
imageUrl
String
required
The URL of the image to load and display.

​
Size Properties

​
width
double?
The width of the image. If null, the image will size itself based on its content.
​
height
double?
The height of the image. If null, the image will size itself based on its content.
​
fit
BoxFit
default:"BoxFit.cover"
How to inscribe the image into the space allocated during layout.

​
State Widgets

​
placeholder
Widget?
Widget displayed while the image is loading. If null, a default loading indicator is shown.
​
errorWidget
Widget?
Widget displayed when an error occurs while loading the image. If null, a default error widget is shown.

​
Network Properties

​
httpHeaders
Map<String, String>?
The HTTP headers to use when loading the image.

​
Configuration Objects

​
cacheConfig
NbxImageCacheConfig
default:"NbxImageCacheConfig()"
Cache configuration options for memory and disk caching.
​
animationConfig
NbxImageAnimationConfig
default:"NbxImageAnimationConfig()"
Animation configuration for fade-in/fade-out effects.
​
progressConfig
NbxImageProgressConfig
default:"NbxImageProgressConfig()"
Progress indicator configuration options.
​
styleConfig
NbxImageStyleConfig
default:"NbxImageStyleConfig()"
Style configuration for borders, shadows, and filters.

​
Configuration Classes

​
NbxImageCacheConfig

Controls image caching behavior.
​
memCacheWidth
int?
Maximum width for the in-memory cache. Null means no constraint.
​
memCacheHeight
int?
Maximum height for the in-memory cache. Null means no constraint.
​
maxWidthDiskCache
int?
Maximum width for the disk cache.
​
maxHeightDiskCache
int?
Maximum height for the disk cache.
​
cacheKey
String?
Custom cache key. If null, the image URL is used.
​
useOldImageOnUrlChange
bool
default:"false"
Whether to keep displaying the old image when the URL changes.
​
cacheManager
BaseCacheManager?
Custom cache manager instance.

​
NbxImageAnimationConfig

Controls fade animations.
​
fadeInDuration
Duration
default:"Duration(milliseconds: 300)"
Duration of the fade-in animation when the image loads.
​
fadeOutDuration
Duration
default:"Duration(milliseconds: 300)"
Duration of the fade-out animation when the placeholder hides.
​
fadeInCurve
Curve
default:"Curves.easeOut"
Curve for the fade-in animation.
​
fadeOutCurve
Curve
default:"Curves.easeIn"
Curve for the fade-out animation.

​
NbxImageProgressConfig

Controls the loading progress indicator.
​
progressIndicatorBuilder
ProgressIndicatorBuilder?
Custom progress indicator builder. When provided, overrides the default.
​
progressIndicatorSize
Size
default:"Size(20, 20)"
Size of the default progress indicator.
​
progressIndicatorColor
Color?
Color of the progress indicator.
​
progressIndicatorStrokeWidth
double
default:"2.0"
Stroke width for the circular progress indicator.
​
progressIndicatorBackgroundColor
Color?
Background color of the progress indicator track.
​
progressIndicatorCircular
bool
default:"true"
Whether to use a circular (true) or linear (false) progress indicator.

​
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 be repeated if it doesn’t fill its bounds.
​
matchTextDirection
bool
default:"false"
Whether to match the text direction for the image.

​
Factory Constructors

​
NbxNetworkImage.circular

Creates a circular network image. 
NbxNetworkImage.circular(
  imageUrl: 'https://example.com/avatar.jpg',
  radius: 50,
  fit: BoxFit.cover,
)
​
imageUrl
String
required
URL of the image.
​
radius
double
required
Radius of the circular image.
​
fit
BoxFit
default:"BoxFit.cover"
How to fit the image.
​
placeholder
Widget?
Custom placeholder widget.
​
errorWidget
Widget?
Custom error widget.
​
borderRadius
BorderRadius?
Override border radius (defaults to circular).
​
border
BoxBorder?
Border around the image.
​
shadow
List<BoxShadow>?
Box shadows.

​
NbxNetworkImage.square

Creates a square network image. 
NbxNetworkImage.square(
  imageUrl: 'https://example.com/thumbnail.jpg',
  size: 100,
  borderRadius: BorderRadius.circular(8),
)
​
imageUrl
String
required
URL of the image.
​
size
double
required
Size of the square image (width and height).
​
fit
BoxFit
default:"BoxFit.cover"
How to fit the image.
​
placeholder
Widget?
Custom placeholder widget.
​
errorWidget
Widget?
Custom error widget.
​
borderRadius
BorderRadius?
Border radius.
​
border
BoxBorder?
Border around the image.
​
shadow
List<BoxShadow>?
Box shadows.

​
NbxNetworkImage.rounded

Creates a network image with rounded corners. 
NbxNetworkImage.rounded(
  imageUrl: 'https://example.com/photo.jpg',
  width: 300,
  height: 200,
  borderRadius: 16,
)
​
imageUrl
String
required
URL of the image.
​
width
double?
Width of the image.
​
height
double?
Height of the image.
​
borderRadius
double
required
Border radius value.
​
fit
BoxFit
default:"BoxFit.cover"
How to fit the image.
​
placeholder
Widget?
Custom placeholder widget.
​
errorWidget
Widget?
Custom error widget.
​
border
BoxBorder?
Border around the image.
​
shadow
List<BoxShadow>?
Box shadows.

​
Examples

​
Basic Image

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

​
Circular Avatar

NbxNetworkImage.circular(
  imageUrl: 'https://example.com/avatar.jpg',
  radius: 40,
  border: Border.all(color: Colors.white, width: 2),
  shadow: [
    BoxShadow(
      color: Colors.black26,
      blurRadius: 8,
      offset: Offset(0, 2),
    ),
  ],
)

​
With Custom Cache

NbxNetworkImage(
  imageUrl: 'https://example.com/large-image.jpg',
  width: 400,
  height: 300,
  cacheConfig: NbxImageCacheConfig(
    memCacheWidth: 800,
    memCacheHeight: 600,
    maxWidthDiskCache: 1000,
    maxHeightDiskCache: 1000,
  ),
)

​
With Custom Progress Indicator

NbxNetworkImage(
  imageUrl: 'https://example.com/image.jpg',
  width: 300,
  height: 200,
  progressConfig: NbxImageProgressConfig(
    progressIndicatorColor: Colors.blue,
    progressIndicatorSize: Size(30, 30),
    progressIndicatorStrokeWidth: 3.0,
  ),
)

​
With Custom Placeholder and Error

NbxNetworkImage(
  imageUrl: 'https://example.com/image.jpg',
  width: 300,
  height: 200,
  placeholder: Center(
    child: CircularProgressIndicator(),
  ),
  errorWidget: Center(
    child: Column(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        Icon(Icons.error, size: 48, color: Colors.red),
        SizedBox(height: 8),
        Text('Failed to load image'),
      ],
    ),
  ),
)

​
With Border and Shadow

NbxNetworkImage(
  imageUrl: 'https://example.com/image.jpg',
  width: 300,
  height: 200,
  styleConfig: NbxImageStyleConfig(
    borderRadius: BorderRadius.circular(12),
    border: Border.all(color: Colors.grey, width: 2),
    shadow: [
      BoxShadow(
        color: Colors.black12,
        blurRadius: 10,
        offset: Offset(0, 4),
      ),
    ],
  ),
)

​
With HTTP Headers

NbxNetworkImage(
  imageUrl: 'https://api.example.com/image.jpg',
  width: 300,
  height: 200,
  httpHeaders: {
    'Authorization': 'Bearer token123',
    'Custom-Header': 'value',
  },
)

​
With Color Filter

NbxNetworkImage(
  imageUrl: 'https://example.com/image.jpg',
  width: 300,
  height: 200,
  styleConfig: NbxImageStyleConfig(
    color: Colors.blue.withOpacity(0.3),
    colorBlendMode: BlendMode.color,
  ),
)

​
Thumbnail Grid

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

​
See Also