ZenQueryConsumer<T> class

A self-contained widget that creates, fetches, and renders a ZenQuery without requiring a separate controller or module.

Perfect for simple, stateless data-display use-cases — analogous to useQuery in React/TanStack Query.

Basic usage:

ZenQueryConsumer<User>(
  queryKey: 'user:123',
  fetcher: (_) => api.getUser(123),
  data: (user) => UserCard(user),
)

With all state handlers:

ZenQueryConsumer<User>(
  queryKey: 'user:123',
  fetcher: (_) => api.getUser(123),
  data: (user) => UserProfile(user),
  loading: () => const CircularProgressIndicator(),
  error: (err, retry) => ErrorView(err, onRetry: retry),
  idle: () => const SizedBox.shrink(),
)

With config:

ZenQueryConsumer<List<Post>>(
  queryKey: 'posts',
  fetcher: (_) => api.getPosts(),
  config: ZenQueryConfig(staleTime: Duration(minutes: 5)),
  data: (posts) => PostList(posts),
)

When to use ZenQueryConsumer vs ZenQueryBuilder

Scenario	Use
Simple data display, no shared state	`ZenQueryConsumer`
Query shared across multiple widgets	`ZenQueryBuilder` + controller
Mutations + queries together	`ZenQueryBuilder` + controller
Pagination / infinite scroll	`ZenQueryBuilder` + controller

Lifecycle

The internal ZenQuery is created once when the widget mounts and disposed when the widget is removed from the tree. If queryKey changes, the old query is disposed and a new one is created.

Inheritance

Constructors

ZenQueryConsumer({Key? key, required Object queryKey, required ZenQueryFetcher<T> fetcher, required Widget data(T data), Widget loading()?, Widget error(Object error, VoidCallback retry)?, Widget idle()?, ZenQueryConfig<T>? config, T? initialData, bool autoFetch = true, bool showStaleData = true}): const

Properties

autoFetch → bool: Whether to automatically fetch when the widget mounts. Defaults to true.
final
config → ZenQueryConfig<T>?: Query configuration — stale time, caching, retry policy etc.
final
data → Widget Function(T data): Builder for the success state. Required.
final
error → Widget Function(Object error, VoidCallback retry)?: Builder for the error state with a retry callback. Defaults to the built-in ZenQueryBuilder error UI.
final
fetcher → ZenQueryFetcher<T>: The async function that fetches data.
final
hashCode → int: The hash code for this object.
no setterinherited
idle → Widget Function()?: Builder for the idle state (before the first fetch). Defaults to SizedBox.shrink.
final
initialData → T?: Initial data shown before the first fetch completes.
final
key → Key?: Controls how one widget replaces another widget in the tree.
finalinherited
loading → Widget Function()?: Builder for the loading state. Defaults to a centered CircularProgressIndicator.
final
queryKey → Object: Unique key for caching and deduplication. Matches the same key in other ZenQueryConsumer or ZenQueryBuilder widgets to share cached data.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
showStaleData → bool: Whether to show stale data while a background refetch is in progress. Defaults to true.
final

Methods

createElement() → StatefulElement: Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<ZenQueryConsumer<T>>: 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
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