Search

The Search component allows users to search for Storyteller Clips and Stories. As users type, a list of suggestions will appear, from which users can either select a suggestion or search using their entered term. Results are categorized by type into Stories and Clips. The current native versions also support tenant-configured Articles results. Filters allow users to narrow down their search results, enabling them to find specific content that meets their criteria more efficiently. For instance, users can apply filters such as date posted, content type or they can sort it by certain criteria.

The Articles behavior described here was audited against a pre-release Flutter 12.1.2 snapshot with Android 12.1.2 and iOS 11.8.0. Published Flutter 12.2.0 uses Android 12.2.0 and iOS 11.9.1; consult Changelog for released dependencies. Native configuration can hide filter sections or content types.

Search Filters

Date Posted possible values:

• All - default value
• Past 24 hours
• Last Week
• Last Month
• Last Year

Content Type possible values:

• All - default value
• Stories
• Clips
• Articles - when configured for the tenant in the current native Search experience

Sort By values:

• Relevance - default value
• Like Count
• Share Count
• Date Posted

How to Use

The Search feature must first be enabled by the Storyteller team for your specific tenant. Once enabled, the Search functionality will be available within the Story and Clip players.

Additional Search functionality is available through the Storyteller class:

Check if Search is Enabled

After successful initialization, use isSearchEnabled() to check whether the current API key enables search. Availability comes from native tenant settings; Flutter does not expose filter or query configuration parameters.

final isEnabled = await Storyteller.isSearchEnabled();
if (isEnabled) {
  print('Search is enabled');
} else {
  print('Search is not enabled');
}

Open Search

Use openSearch() to open the Search component from anywhere in the app. iOS dismisses an existing Storyteller player before presenting Search. Android launches its native Search activity when search is enabled and an activity is attached; do not rely on the same dismissal ordering.

// After initialization, open search only if enabled
if (await Storyteller.isSearchEnabled()) {
  await Storyteller.openSearch();
}

Example: Adding a Search Button

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

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

  @override
  Widget build(BuildContext context) {
    return FutureBuilder<bool>(
      future: Storyteller.isSearchEnabled(),
      builder: (context, snapshot) {
        if (!snapshot.hasData || !snapshot.data!) {
          return const SizedBox.shrink(); // Hide while loading or unavailable
        }

        return IconButton(
          icon: const Icon(Icons.search),
          onPressed: () async {
            await Storyteller.openSearch();
          },
        );
      },
    );
  }
}

The Showcase home screen wires these APIs end-to-end: initState queries availability via Storyteller.isSearchEnabled() and the search icon triggers Storyteller.openSearch().

Customization

Certain UI parts of the Search component can be customized through theming. For more information, see the Themes documentation - Search section.

You can customize:

• Back icon
• Filter heading font, size, line height, text case, and color

Declare assets/icons/custom_back.png under flutter.assets in your app's pubspec.yaml before using this example; the filename and case must match.

Example: Customizing Search Appearance

final theme = StorytellerTheme(
  light: ThemeType(
    search: ThemeSearch(
      backIcon: ThemeImage(filePath: 'assets/icons/custom_back.png'),
      heading: ThemeTitle(
        textSize: 24.0,
        lineHeight: 30.0,
        textCase: 'upper',
        textColor: '#000000',
      ),
    ),
  ),
);

await Storyteller.setTheme(theme);

If Search does not open, verify initialization, availability for the current key, and that your app is foregrounded. See Troubleshooting.