octo_image 0.2.1

  • Readme
  • Changelog
  • Example
  • Installing
  • 100

OctoImage #

pub package Build Status codecov

An image library for showing placeholders, error widgets and transform your image.

Recommended to use with CachedNetworkImage version 2.2.0 or newer.

Getting Started #

The OctoImage widget needs an ImageProvider to show the image. You can either supply the widget with a placeholder or progress indicator, an ImageBuilder and/or an error widget.

However, what OctoImage makes is the use of OctoSets. OctoSets are predefined combinations placholders, imagebuilders and error widgets.

So, either set the all the components yourself:

OctoImage(
  image: CachedNetworkImageProvider(
      'https://blurha.sh/assets/images/img1.jpg'),
  placeholderBuilder: OctoPlaceholder.blurHash(
    'LEHV6nWB2yk8pyo0adR*.7kCMdnj',
  ),
  errorBuilder: OctoError.icon(color: Colors.red),
  fit: BoxFit.cover,
);

Or use an OctoSet:

OctoImage.fromSet(
  fit: BoxFit.cover,
  image: CachedNetworkImageProvider(
    'https://upload.wikimedia.org/wikipedia/commons/thumb/4/4e/Macaca_nigra_self-portrait_large.jpg/1024px-Macaca_nigra_self-portrait_large.jpg',
  ),
  octoSet: OctoSet.circleAvatar(
    backgroundColor: Colors.red,
    text: Text("M"),
  ),
);

The CircleAvatar set shows a colored circle with the text inside during loading and when the image failed loading. When the image loads it animates to the image clipped as a circle.

ImageProviders #

The recommended one is CachedNetworkImageProvider as that supports the progress indicator, error and caching. It also works on Android, iOS, web and macOS, although without caching on web. Make sure you use at least version 2.2.0.

Second best is NetworkImage, but any ImageProvider works in theory. However, for some ImageProviders (such as MemoryImage) it doesn't make sense to use OctoImage.

Placeholders and progress indicators #

You should use either a placeholder or a progress indicator, but not both. Placeholders are only build once when the image starts loading, but progress indicators are rebuild every time new progress information is received. So if you don't use that progress indication, for example with a static image, than you should use a placeholder.

The most simple progress indicators use a CircularProgressIndicator.

OctoImage(
  image: image,
  progressIndicatorBuilder: (context) => 
    const CircularProgressIndicator(),
),
OctoImage(
  image: image,
  progressIndicatorBuilder: (context, progress) {
    double value;
    if (progress != null && progress.expectedTotalBytes != null) {
      value =
          progress.cumulativeBytesLoaded / progress.expectedTotalBytes;
    }
    return CircularProgressIndicator(value: value);
  },
),

However, because these are used so often, we prebuild these widgets for you. Just use OctoProgressIndicator.circularProgressIndicator()

OctoImage(
  image: image,
  progressIndicatorBuilder: OctoProgressIndicator.circularProgressIndicator(),
),

All included placeholders and progress indicators:

OctoPlaceholderExplanation
blurHashShows a BlurHash image
circleAvatarShows a colored circle with a text
circularProgressIndicatorShows a circularProgressIndicator with indeterminate progress.
frameShows the Flutter Placeholder
OctoProgressIndicatorExplanation
circularProgressIndicatorShows a simple CircularProgressIndicator

Error widgets #

Error widgets are shown when the ImageProvider throws an error because the image failed loading. You can build a custom widget, or use the prebuild widgets:

OctoImage(
  image: image,
  errorBuilder: (context, error, stacktrace) =>
    const Icon(Icons.error),
);
OctoImage(
  image: image,
  errorBuilder: OctoError.icon(),
),

All included error widgets are:

OctoErrorExplanation
blurHashShows a BlurHash placeholder with an error icon.
circleAvatarShows a colored circle with a text
iconShows an icon, default to Icons.error
placeholderWithErrorIconShows any placeholder with an icon op top.

Image builders #

Image builders can be used to adapt the image before it is shown. For example the circleAvatar clips the image in a circle, but you could also add an overlay or anything else.

The builder function supplies a context and a child. The child is the image widget that is rendered.

An example that shows the image with 50% opacity:

OctoImage(
  image: image,
  imageBuilder: (context, child) => Opacity(
    opacity: 0.5,
    child: child,
  ),
),

A prebuild image transformer that clips the image as a circle:

OctoImage(
  image: image,
  imageBuilder: OctoImageTransformer.circleAvatar(),
),

All included image transformers are:

OctoImageTransformerExplanation
circleAvatarClips the image in a circle

OctoSets #

You get the most out of OctoImage when you use OctoSets. These sets contain a combination of a placeholder or progress indicator, an image builder and/or an error widget builder. It always contains at least a placeholder or progress indicator and an error widget.

You can use them with OctoImage.fromSet:

OctoImage.fromSet(
  image: image,
  octoSet: OctoSet.blurHash('LEHV6nWB2yk8pyo0adR*.7kCMdnj'),
),

All included OctoSets are:

OctoSetExplanation
blurHashShows a blurhash as placeholder and error widget. When an error is thrown an icon is shown on top.
circleAvatarShows a colored circle with text during load and error. Clips the image after successful load.
circularIndicatorAndIconShows a circularProgressIndicator with or without progress and an icon on error.

Contribute #

If you would like to contribute to the plugin (e.g. by improving the documentation, solving a bug or adding a cool new feature), please carefully review our contribution guide and send us your pull request.

PR's with any new prebuild widgets or sets are highly appreciated.

Support #

  • Feel free to open an issue. Make sure to use one of the templates!
  • Commercial support is available. Integration with your app or services, samples, feature request, etc. Email: hello@baseflow.com
  • Powered by: baseflow.com

[0.2.1] - 2020-06-04 #

  • Make whole widget, including placeholder and error widgets, adhere to the height and width set.

[0.2.0] - 2020-05-28 #

  • Made gaplessPlayback fade from one image to the next

[0.1.1] - 2020-05-20 #

  • Update dependency for blurHash

[0.1.0] - 2020-05-14 #

  • Removed headers as they are not used for anything
  • Added gaplessPlayback, works just like in Image: it keeps the old image visible when a new image is being loaded by the same widget.
  • Changed how default parameter values work preventing setting them to null.

[0.0.1] - 2020-05-08 #

  • Initial release with already lots of great features :)

example/lib/main.dart

import 'package:cached_network_image/cached_network_image.dart';
import 'package:flutter/material.dart';
import 'package:octo_image/octo_image.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'OctoImage Demo',
      theme: ThemeData(),
      home: OctoImagePage(),
    );
  }
}

class OctoImagePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('OctoImage Demo'),
      ),
      body: ListView(
        children: [
          _customImage(),
          SizedBox(height: 16),
          _simpleBlur(),
          SizedBox(height: 16),
          _circleAvatar(),
        ],
      ),
    );
  }

  Widget _customImage() {
    return SizedBox(
      height: 150,
      child: OctoImage(
        image: CachedNetworkImageProvider('https://via.placeholder.com/150'),
        progressIndicatorBuilder: (context, progress) {
          double value;
          if (progress != null && progress.expectedTotalBytes != null) {
            value =
                progress.cumulativeBytesLoaded / progress.expectedTotalBytes;
          }
          return CircularProgressIndicator(value: value);
        },
        errorBuilder: (context, error, stacktrace) => Icon(Icons.error),
      ),
    );
  }

  Widget _simpleBlur() {
    return AspectRatio(
      aspectRatio: 269 / 173,
      child: OctoImage(
        image: CachedNetworkImageProvider(
            'https://blurha.sh/assets/images/img1.jpg'),
        placeholderBuilder: OctoPlaceholder.blurHash(
          'LEHV6nWB2yk8pyo0adR*.7kCMdnj',
        ),
        errorBuilder: OctoError.icon(color: Colors.red),
        fit: BoxFit.cover,
      ),
    );
  }

  Widget _circleAvatar() {
    return SizedBox(
      height: 75,
      child: OctoImage.fromSet(
        fit: BoxFit.cover,
        image: CachedNetworkImageProvider(
          'https://upload.wikimedia.org/wikipedia/commons/thumb/4/4e/Macaca_nigra_self-portrait_large.jpg/1024px-Macaca_nigra_self-portrait_large.jpg',
        ),
        octoSet: OctoSet.circleAvatar(
          backgroundColor: Colors.red,
          text: Text("M"),
        ),
      ),
    );
  }
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  octo_image: ^0.2.1

2. Install it

You can install packages from the command line:

with Flutter:


$ flutter pub get

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:octo_image/octo_image.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
99
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
100
Learn more about scoring.

We analyzed this package on Jul 11, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.4
  • pana: 0.13.14
  • Flutter: 1.17.5

Analysis suggestions

Package not compatible with SDK dart

Because:

  • octo_image that is a package requiring null.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.7.0 <3.0.0
flutter 0.0.0
flutter_blurhash >=0.4.1 <0.6.0 0.5.0
Transitive dependencies
collection 1.14.12 1.14.13
meta 1.1.8 1.2.2
sky_engine 0.0.99
typed_data 1.1.6 1.2.0
vector_math 2.0.8 2.1.0-nullsafety
Dev dependencies
effective_dart ^1.2.0
flutter_test
transparent_image ^1.0.0