Effects Cloud Filters: Flutter
Effects / Guides / Filters / Cloud Filters: Flutter

Download and apply a Nosmai Cloud Filter in Flutter

Updated October 28, 2026

List Cloud Filters, display cached thumbnails with NosmaiFilterPreview, download the selected filter, and apply it to the active camera preview.

Feature access

Cloud Filters must be enabled for your Nosmai project before you can browse, download, cache, apply, or remove cloud-delivered effects. Review your project's enabled features in Nosmai Console.

Prerequisites

  • A working Flutter quickstart
  • Cloud Filters enabled for the project
  • Successful SDK initialization before mounting the thumbnail widgets

Request the catalog

final filters = await NosmaiFlutter.instance.getCloudFilters(
  filterType: NosmaiCloudFilterType.effects,
  page: 1,
  limit: 20,
);

Other typed values include filter, background, and beautyEffect.

Display catalog thumbnails

NosmaiFilterPreview displays a thumbnail for a filter or effect in a picker, list, or grid. It manages preview-image loading and available cached thumbnails. It can also obtain a preview from an already available local package when the preferred image source is unavailable.

Displaying a thumbnail may download its image. The widget does not download the effect package, apply a filter, or start the camera. A visible thumbnail therefore does not mean the effect itself is downloaded or active.

Display one thumbnail

Import the public package:

import 'package:flutter/material.dart';
import 'package:nosmai_effects_sdk/nosmai_effects_sdk.dart';

Pass a catalog item directly to the widget:

NosmaiFilterPreview(
  filter: filter,
  width: 80,
  height: 80,
  fit: BoxFit.cover,
)

filter is a NosmaiFilter from a successful SDK catalog request. There is no need to extract or decode its preview field yourself.

Add a filter grid

Keep the filters list from the catalog request in application state. Fetch the catalog from the screen's initialization or refresh flow rather than from build.

Use the following widget inside a parent with a bounded height, such as an Expanded or a SizedBox:

class FilterThumbnailGrid extends StatelessWidget {
  const FilterThumbnailGrid({
    super.key,
    required this.filters,
    required this.onSelected,
  });

  final List<NosmaiFilter> filters;
  final ValueChanged<NosmaiFilter> onSelected;

  @override
  Widget build(BuildContext context) {
    if (filters.isEmpty) {
      return const Center(child: Text('No filters available'));
    }

    return GridView.builder(
      gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
        crossAxisCount: 3,
        crossAxisSpacing: 12,
        mainAxisSpacing: 12,
        childAspectRatio: 0.8,
      ),
      itemCount: filters.length,
      itemBuilder: (context, index) {
        final filter = filters[index];
        return InkWell(
          onTap: () => onSelected(filter),
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.stretch,
            children: [
              Expanded(
                child: ClipRRect(
                  borderRadius: BorderRadius.circular(12),
                  child: NosmaiFilterPreview(
                    filter: filter,
                    fit: BoxFit.cover,
                    decodeSize: 256,
                    placeholder: (_) => const ColoredBox(
                      color: Color(0xFFEDEFF2),
                      child: Center(
                        child: SizedBox.square(
                          dimension: 20,
                          child: CircularProgressIndicator(strokeWidth: 2),
                        ),
                      ),
                    ),
                    errorBuilder: (_) => const ColoredBox(
                      color: Color(0xFFEDEFF2),
                      child: Center(child: Icon(Icons.image_not_supported)),
                    ),
                  ),
                ),
              ),
              const SizedBox(height: 8),
              Text(
                filter.displayName,
                maxLines: 1,
                overflow: TextOverflow.ellipsis,
                textAlign: TextAlign.center,
              ),
            ],
          ),
        );
      },
    );
  }
}

The application owns onSelected. Connect it to the download and apply flow below when the user selects an item.

Customize the thumbnail

ParameterPurposeDefault
filterSDK catalog item whose preview should be displayedRequired
width and heightThumbnail layout dimensions in Flutter logical pixelsParent constraints
fitHow the decoded image fills the available spaceBoxFit.cover
alignmentImage alignment within its available spaceAlignment.center
decodeSizeMaximum decoded image dimension in pixels, clamped to 64 through 512256
placeholderWidgetBuilder used while the image loadsBuilt-in image placeholder
errorBuilderWidgetBuilder used when no usable preview is availableBuilt-in image placeholder

placeholder and errorBuilder receive a BuildContext. They do not receive an exception or stack trace. Use decodeSize to match the intended thumbnail size; increasing the layout dimensions does not require a full-resolution image for every catalog item.

Caching and offline behavior

  • Available cached previews can be reused when the picker is reopened.
  • When an image source is unavailable, the widget can fall back to a preview inside an already available local package.
  • A previously unseen cloud thumbnail may require network access. If no usable cached or local preview exists, the widget displays errorBuilder.
  • Thumbnail storage is bounded and may be cleared or reclaimed. Treat it as a convenience cache rather than permanent storage.
  • Thumbnail caching and effect-package downloading are separate operations. Check the SDK download result before applying an effect.

Keep SDK-provided identifiers and metadata with each NosmaiFilter. After a catalog refresh or package download, pass the updated item to the widget so it can use the current metadata and available preview sources.

Download and apply

final filter = filters.first;
final result = await NosmaiFlutter.instance.downloadCloudFilter(
  filter.cloudIdentifier,
);
final path = result['path'] as String?;

if (path == null || path.isEmpty) {
  throw StateError('Cloud Filter download returned no path');
}

await NosmaiFlutter.instance.applyEffect(path);

Remove a cached item only after an explicit user or product action:

await NosmaiFlutter.instance.removeCloudFilter(
  filter.cloudIdentifier,
);

Handle cache eviction

Do not persist path as a permanent asset reference. The cache has no documented cross-platform TTL and the operating system can reclaim it. Query the SDK's downloaded state when the item is selected; if it is missing, call downloadCloudFilter again and use the new returned path.

Verify it worked

  1. Open the picker and confirm names and thumbnails load.
  2. Reopen it and confirm available cached thumbnails can be reused.
  3. Disable network access and check both previously loaded items and an item whose preview has never been loaded.
  4. Confirm that browsing thumbnails alone does not apply a filter.
  5. Select a filter and verify that the application's download/apply handler runs separately.
  6. Close and reopen the filter UI, then apply an already cached effect package with network disabled.

Common errors

SymptomFix
Catalog is emptyCheck cloud capability, type, and native key configuration
Returned path is nullTreat the download as failed and show Retry
Two downloads startStore one Future per cloudIdentifier
Every item displays the error placeholderInitialize the SDK first, check cloud feature access, and use current SDK catalog items
A thumbnail is missing offlineIts image cache may be unavailable and there may be no usable local package preview; keep the fallback visible
Grid reports an unbounded-height errorGive the grid a bounded parent, such as Expanded or a SizedBox
A thumbnail is visible but selecting the filter has no effectConnect onSelected to the documented download and apply flow

Next steps

References

Nosmai

An AR and AI company. Founded on the idea that the next decade of software will be visual, and that the tools for it should be within reach of anyone building.

Newsletter

Product updates and release notes. No spam.

© 2026 nosmai, inc · all rights reserved