FilePreviewContainer class

A highly reusable, enterprise-grade File Preview container and screen.

Features:

📖 Easy Usage Examples:

1. Open as a Full Screen Modal Route:

// Open an Image from Network:
FilePreviewContainer.show(
  context,
  filePath: 'https://example.com/sample.jpg',
  fileType: FileType.image,
  title: 'Profile Picture',
);

// Open a PDF Document from Local Storage:
FilePreviewContainer.show(
  context,
  filePath: '/path/to/invoice.pdf',
  fileType: FileType.pdf,
  sourceType: FileSourceType.file,
  title: 'Tax Invoice',
  appBarBackgroundColor: Colors.indigo,
  controlsBackgroundColor: Colors.indigo.shade50,
);

2. Create a Dedicated Custom Screen / Page:

class MyInvoicePreviewScreen extends StatelessWidget {
  const MyInvoicePreviewScreen({super.key, required this.pdfUrl});
  final String pdfUrl;

  @override
  Widget build(BuildContext context) {
    return FilePreviewContainer(
      filePath: pdfUrl,
      fileType: FileType.pdf,
      sourceType: FileSourceType.network,
      title: 'Monthly Invoice',
      actions: [
        IconButton(
          icon: const Icon(Icons.share),
          onPressed: () => shareInvoice(pdfUrl),
        ),
      ],
    );
  }
}

3. Embed Directly as an Inline Widget (Inside Custom Layout / Tab):

class InlineDocumentViewerCard extends StatelessWidget {
  const InlineDocumentViewerCard({super.key});

  @override
  Widget build(BuildContext context) {
    return ClipRRect(
      borderRadius: BorderRadius.circular(16),
      child: SizedBox(
        height: 350,
        child: FilePreviewContainer(
          filePath: 'assets/sample.pdf',
          fileType: FileType.pdf,
          sourceType: FileSourceType.asset,
          showAppBar: false, // Disables AppBar for embedded containers
        ),
      ),
    );
  }
}
Inheritance
Available extensions

Constructors

FilePreviewContainer({Key? key, required String filePath, required FileType fileType, FileSourceType sourceType = FileSourceType.network, String? title, bool showAppBar = true, List<Widget>? actions, String? heroTag, Color? backgroundColor, Color? appBarBackgroundColor, Color? appBarForegroundColor, Color? controlsBackgroundColor, Color? controlsForegroundColor, Widget? loadingWidget, Widget errorWidgetBuilder(BuildContext context, Object error)?, double minScale = 0.5, double maxScale = 4.0, void onPageChanged(int currentPage, int totalPages)?, ValueChanged<int>? onPdfRendered})
const

Properties

actions → List<Widget>?
Optional custom action buttons in the AppBar.
final
appBarBackgroundColor → Color?
Custom background color for the AppBar.
final
appBarForegroundColor → Color?
Custom icon/text color for the AppBar.
final
backgroundColor → Color?
Custom background color of the viewer container/scaffold.
final
controlsBackgroundColor → Color?
Custom background color for the PDF bottom page controls.
final
controlsForegroundColor → Color?
Custom icon/text color for the PDF bottom page controls.
final
errorWidgetBuilder → Widget Function(BuildContext context, Object error)?
Custom error builder when image or PDF fails to load.
final
filePath → String
The target file URL, local file system path, or bundled asset path.
final
fileType → FileType
The type of file to render (FileType.image or FileType.pdf).
final
hashCode → int
The hash code for this object.
no setterinherited
heroTag → String?
Optional Hero animation tag for smooth image transitions.
final
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
loadingWidget → Widget?
Custom loading widget. Defaults to CircularProgressIndicator.adaptive.
final
maxScale → double
Maximum interactive zoom scale for images.
final
minScale → double
Minimum interactive zoom scale for images.
final
onPageChanged → void Function(int currentPage, int totalPages)?
Callback when PDF active page changes.
final
onPdfRendered → ValueChanged<int>?
Callback when PDF rendering completes.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
showAppBar → bool
Whether to render the Scaffold AppBar (default true). Set to false when embedding as a container.
final
sourceType → FileSourceType
Origin source type (FileSourceType.network, FileSourceType.file, or FileSourceType.asset).
final
title → String?
Optional AppBar title.
final

Methods

createElement() → StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<FilePreviewContainer>
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
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
onAppEvent<E extends AppEvent>(AppEventHandler<E> onEvent) → Widget

Available on Widget, provided by the AppEventListenerExtension extension

Wraps this widget with an AppEventListener listening to a single event E.
onAppEventPattern(AppEventRawHandler onEvent) → Widget

Available on Widget, provided by the AppEventListenerExtension extension

Wraps this widget with a pattern-matching AppEventListener.
onAppEvents(List<OnEvent<AppEvent>> events) → Widget

Available on Widget, provided by the AppEventListenerExtension extension

Wraps this widget with an AppEventListener listening to multiple OnEvents.
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

Operators

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

Static Methods

show<T>(BuildContext context, {required String filePath, required FileType fileType, FileSourceType sourceType = FileSourceType.network, String? title, bool showAppBar = true, List<Widget>? actions, String? heroTag, Color? backgroundColor, Color? appBarBackgroundColor, Color? appBarForegroundColor, Color? controlsBackgroundColor, Color? controlsForegroundColor, Widget? loadingWidget, Widget errorWidgetBuilder(BuildContext context, Object error)?, double minScale = 0.5, double maxScale = 4.0, void onPageChanged(int currentPage, int totalPages)?, ValueChanged<int>? onPdfRendered, bool useRootNavigator = true}) → Future<T?>
Helper factory to launch the FilePreviewContainer as a full modal route.