Image

Renders a raster image, adapting to what the surface can do.

Import: package:fleury/fleury.dart, or package:fleury/fleury_core.dart in browser code.

Usage

Image.bytes(logoBytes, fit: ImageFit.contain)
// Image.file(...) needs dart:io — use bytes/decoded in embeds

Details

On surfaces that support inline pixels (MediaQuery’s SurfaceCapabilities.images reports placements — a Kitty/iTerm2/ Sixel terminal, or a browser surface) the widget records a neutral image placement and the presenter renders true pixels. Everywhere else it paints glyph art: each terminal cell holds two vertical “pixels”, the top half drawn via the foreground of ▀, the bottom half via its background — 24-bit color per half-cell on truecolor terminals. With 256 or 16 colors, the widget reduces the image’s colors itself, dithering to smooth the result; with no color support it draws without color. Both paths resolve fit through the same core geometry, so a letterbox lands on the same cells either way.

Decoding is synchronous and cached on the ImageSource; the widget itself is cheap to rebuild. For HTTP or other async sources, decode upstream and pass via ImageSource.decoded.

Constructors

`Image()`

Parameter	Type	Default	Description
`source:`	`ImageSource`	required	Pixel source decoded when the widget is mounted or replaced.
`fit:`	`ImageFit`	`ImageFit.contain`	Scaling and cropping policy within the widget’s allotted cell area.
`glyph:`	`ImageGlyph`	`ImageGlyph.halfBlock`	Symbol palette for the glyph-art fallback. `ImageGlyph.halfBlock` is the conservative default; `ImageGlyph.quarterBlock` roughly doubles horizontal resolution at the cost of more font-glyph reliance. Ignored when the surface renders inline pixels (`SurfaceCapabilities.images` reports placements) — that path is already pixel-perfect and needs no palette.
`backgroundColor:`	`Color?`	—	For the glyph-art fallback, semitransparent pixels (0 < α < 255) are alpha-composited against this color when non-null: `out = α · src + (1−α) · bg`. Fully-transparent pixels are also flattened to `backgroundColor`. True-pixel placements retain the source alpha. More
`semanticLabel:`	`String?`	—	Describes the image for screen readers, agents, tests, and inspectors. More

backgroundColor: When null, cells whose pixels are all transparent stay empty (showing the terminal’s own background), a transparent half of a half-block cell shows the background too, and semitransparent pixels are weighted by their α in the area average — readable but doesn’t match what designers expect from a compositor. Provide backgroundColor (typically the surrounding container’s color) when transparent PNGs need crisp edges against a known surface.
semanticLabel: Leave null for decorative images. Capability and fallback state is still exposed so diagnostics can explain how the image rendered.

`Image.file()`

Shorthand for Image(source: ImageSource.file(path)) — the common path for asset-style usage. Mirrors Flutter’s Image.file(File(path)).

Browser hosts should use Image.bytes or Image.decoded instead.

Parameter	Type	Default	Description
`path`	`String`	required	File path read by the synchronously decoded, shared file cache.
`fit:`	`ImageFit`	`ImageFit.contain`	Scaling and cropping policy within the widget’s allotted cell area.
`glyph:`	`ImageGlyph`	`ImageGlyph.halfBlock`	Symbol palette for the glyph-art fallback. `ImageGlyph.halfBlock` is the conservative default; `ImageGlyph.quarterBlock` roughly doubles horizontal resolution at the cost of more font-glyph reliance. Ignored when the surface renders inline pixels (`SurfaceCapabilities.images` reports placements) — that path is already pixel-perfect and needs no palette.
`backgroundColor:`	`Color?`	—	For the glyph-art fallback, semitransparent pixels (0 < α < 255) are alpha-composited against this color when non-null: `out = α · src + (1−α) · bg`. Fully-transparent pixels are also flattened to `backgroundColor`. True-pixel placements retain the source alpha. More
`semanticLabel:`	`String?`	—	Describes the image for screen readers, agents, tests, and inspectors. More

`Image.bytes()`

Shorthand for Image(source: ImageSource.bytes(bytes)).

Parameter	Type	Default	Description
`bytes`	`Uint8List`	required	Encoded image bytes decoded synchronously by the created source.
`fit:`	`ImageFit`	`ImageFit.contain`	Scaling and cropping policy within the widget’s allotted cell area.
`glyph:`	`ImageGlyph`	`ImageGlyph.halfBlock`	Symbol palette for the glyph-art fallback. `ImageGlyph.halfBlock` is the conservative default; `ImageGlyph.quarterBlock` roughly doubles horizontal resolution at the cost of more font-glyph reliance. Ignored when the surface renders inline pixels (`SurfaceCapabilities.images` reports placements) — that path is already pixel-perfect and needs no palette.
`backgroundColor:`	`Color?`	—	For the glyph-art fallback, semitransparent pixels (0 < α < 255) are alpha-composited against this color when non-null: `out = α · src + (1−α) · bg`. Fully-transparent pixels are also flattened to `backgroundColor`. True-pixel placements retain the source alpha. More
`semanticLabel:`	`String?`	—	Describes the image for screen readers, agents, tests, and inspectors. More

`Image.decoded()`

Shorthand for Image(source: ImageSource.decoded(decoded)) — pass an already-decoded package:image Image (e.g. from an HTTP fetch, generated programmatically, or transformed).

Parameter	Type	Default	Description
`decoded`	`img.Image`	required	Already-decoded pixels to render directly.
`fit:`	`ImageFit`	`ImageFit.contain`	Scaling and cropping policy within the widget’s allotted cell area.
`glyph:`	`ImageGlyph`	`ImageGlyph.halfBlock`	Symbol palette for the glyph-art fallback. `ImageGlyph.halfBlock` is the conservative default; `ImageGlyph.quarterBlock` roughly doubles horizontal resolution at the cost of more font-glyph reliance. Ignored when the surface renders inline pixels (`SurfaceCapabilities.images` reports placements) — that path is already pixel-perfect and needs no palette.
`backgroundColor:`	`Color?`	—	For the glyph-art fallback, semitransparent pixels (0 < α < 255) are alpha-composited against this color when non-null: `out = α · src + (1−α) · bg`. Fully-transparent pixels are also flattened to `backgroundColor`. True-pixel placements retain the source alpha. More
`semanticLabel:`	`String?`	—	Describes the image for screen readers, agents, tests, and inspectors. More

Source

Image is defined in packages/fleury/lib/src/catalog/image.dart.

Category: Text & content · All widgets

Example · editable

class _PhotoViewerState extends State<PhotoViewer> {
  late Future<img.Image> _photo = widget.loadPhoto();

  void _reload() => setState(() => _photo = widget.loadPhoto());

  @override
  Widget build(BuildContext context) => FutureBuilder<img.Image>(
    future: _photo,
    builder: (context, snapshot) {
      final loading = snapshot.connectionState == ConnectionState.waiting;
      if (snapshot.hasError && !loading) {
        return Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            const Text('Could not load a photo.'),
            Button(text: 'Retry', onPressed: _reload),
          ],
        );
      }

      final photo = snapshot.data;
      if (photo == null) return const Text('Loading a photo from the web…');
      return Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text(loading ? 'Loading a new photo…' : 'Random landscape'),
          SizedBox(
            width: 48,
            height: 10,
            child: Image.decoded(
              photo,
              fit: ImageFit.cover,
              semanticLabel: 'Random landscape photo',
            ),
          ),
          Button(text: 'Load another', onPressed: loading ? null : _reload),
        ],
      );
    },
  );
}

import 'package:http/http.dart' as http;
import 'package:image/image.dart' as img;

Future<img.Image> fetchPhoto(int seed) async {
  final response = await http.get(
    Uri.parse('https://picsum.photos/seed/fleury-$seed/480/240.jpg'),
  );
  if (response.statusCode != 200) {
    throw StateError('Photo request failed (${response.statusCode})');
  }
  return img.decodeImage(response.bodyBytes) ??
      (throw const FormatException('Response was not an image'));
}

/// Mounts the photo viewer only after the reader asks for it, so opening a
/// page that embeds this demo sends no request to the photo service.
class _PhotoPreviewState extends State<_PhotoPreview> {
  var _seed = 0;
  var _started = false;

  @override
  Widget build(BuildContext context) => _started
      ? loading.PhotoViewer(loadPhoto: () => loading.fetchPhoto(++_seed))
      : Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            const Text('Photos come from picsum.photos.'),
            Button(
              text: 'Load a photo',
              onPressed: () => setState(() => _started = true),
            ),
          ],
        );
}

Live preview

Live · interactive

click & type to interact ⓘ how this demo runs