TImage class

An image widget with preview, fallback, and optional title/subtitle.

TImage provides an advanced image display with:

  • Network image loading with fallback
  • Click to preview with zoom (using PhotoView)
  • Custom shapes (rounded, circle)
  • Title and subtitle support
  • Aspect ratio control
  • Placeholder images
  • Stable persistent caching via TImageStorage (set forceCache to true)

Basic Usage

TImage(
  url: 'https://example.com/image.jpg',
  size: 100,
)

Circle Image

TImage.circle(
  url: user.avatarUrl,
  size: 60,
  title: user.name,
  subTitle: user.role,
)

Profile Image

TImage.profile(
  url: user.avatarUrl,
  name: user.name,
  role: user.role,
  size: 42,
)

Force-cached Image (IndexedDB / app documents dir)

TImage(
  url: 'https://example.com/image.jpg',
  size: 100,
  forceCache: true,   // stores in IndexedDB (web) or documents dir (mobile)
)

See also:

Inheritance
Mixed-in types
Available extensions

Constructors

TImage({Key? key, String? url, double size = 80, double previewSize = 350, double aspectRatio = 1, String placeholder = 'package:te_widgets/assets/icons/no_image.png', ShapeBorder border = const RoundedRectangleBorder(borderRadius: BorderRadius.all(Radius.circular(12))), double padding = 5, BoxFit fit = BoxFit.cover, Color? color, String? title, String? subTitle, Color? titleColor, Color? subTitleColor, bool disabled = false, VoidCallback? onShow, VoidCallback? onHide, String? cacheKey, BaseCacheManager? cacheManager, TextOverflow? textOverflow, int? maxLines, bool forceCache = false})
Creates an image widget.
const
TImage.circle({Key? key, String? url, double size = 80, double previewSize = 350, double aspectRatio = 1, String placeholder = 'package:te_widgets/assets/icons/no_image.png', ShapeBorder border = const CircleBorder(), double padding = 5, BoxFit fit = BoxFit.contain, Color? color, String? title, String? subTitle, Color? titleColor, Color? subTitleColor, bool disabled = false, VoidCallback? onShow, VoidCallback? onHide, String? cacheKey, BaseCacheManager? cacheManager, int? maxLines, TextOverflow? textOverflow, bool forceCache = false})
Creates a circular image widget.
const

Properties

alignment → TPopupAlignment
Preferred alignment of the popup.
no setteroverride
aspectRatio → double
The aspect ratio of the image.
final
border → ShapeBorder
The border shape of the image.
final
cacheKey → String?
Custom cache key for the image.
final
cacheManager → BaseCacheManager?
Custom cache manager for advanced cache control.
final
color → Color?
Background color for the image container.
final
disabled → bool
Whether the image preview is disabled.
final
fit → BoxFit
How the image should fit within its bounds.
final
forceCache → bool
When true, the image is downloaded once and stored persistently in IndexedDB (web) or the app documents directory (Android/iOS/desktop) via TImageStorage.
final
hashCode → int
The hash code for this object.
no setterinherited
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
maxLines → int?
final
offset → double
Offset from the target widget.
no setterinherited
onHide → VoidCallback?
Callback fired when the preview is hidden.
final
onShow → VoidCallback?
Callback fired when the preview is shown.
final
padding → double
Padding around the image.
final
placeholder → String
The placeholder image path (supports package assets).
final
previewSize → double
The size of the preview when clicked.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
showCloseButton → bool
Whether to show a close button in the popup.
no setterinherited
size → double
The size of the image (width and height for square images).
final
subTitle → String?
Optional subtitle text displayed below the title.
final
subTitleColor → Color?
Custom color for the subtitle text.
final
textOverflow → TextOverflow?
final
title → String?
Optional title text displayed next to the image.
final
titleColor → Color?
Custom color for the title text.
final
url → String?
The URL of the image to display.
final

Methods

box({double minW = 0.0, double minH = 0.0, double maxW = double.infinity, double maxH = double.infinity}) → Widget

Available on Widget, provided by the WidgetX extension

Wraps this widget in a ConstrainedBox to apply layout constraints.
center({bool when = true}) → Widget

Available on Widget, provided by the WidgetX extension

Wraps this widget in a Center widget.
createElement() → StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<TImage>
Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
estimateWidth(BuildContext context) → double

Available on TImage, provided by the TImageWidthX extension

expanded({int flex = 1}) → Widget

Available on Widget, provided by the WidgetX extension

Wraps this widget in an Expanded widget.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
padding([double left = 0.0, double top = 0.0, double right = 0.0, double bottom = 0.0]) → Widget

Available on Widget, provided by the WidgetX extension

Wraps this widget in a Padding with flexible edge control.
paddingSymmetric({double h = 0.0, double v = 0.0}) → Widget

Available on Widget, provided by the WidgetX extension

Wraps this widget in a Padding with symmetric horizontal and vertical spacing.
size({double? w, double? h}) → Widget

Available on Widget, provided by the WidgetX extension

Wraps this widget in a SizedBox to apply fixed width and/or height.
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String
Returns a one-line detailed description of the object.
inherited
toStringShort() → String
A short, textual description of this widget.
inherited
visible(bool visible, {bool maintainState = false}) → Widget

Available on Widget, provided by the WidgetX extension

Wraps this widget in a Visibility widget.
when(bool condition) → Widget

Available on Widget, provided by the WidgetX extension

Returns this widget if condition is true, otherwise returns SizedBox.shrink(). Usage: Text('Hello').when(isVisible)

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Methods

profile({String? url, String? name, String? role, double size = 42, double padding = 5, bool forceCache = false}) → TImage
Creates a profile image with default styling.