flutter_settings_framework library

Declarative settings for Flutter with bilingual search and a Riverpod adapter plus ready-made settings UI.

Core concepts

Riverpod integration

The package ships a Riverpod adapter and Riverpod-based UI (flutter_riverpod is a hard dependency). Use initializeSettings and the SettingsProviders container to wire everything up. Extension methods on WidgetRef (e.g. ref.watchSetting, ref.updateSetting) provide convenient widget-level access.

See README.md for full documentation and usage examples.

Classes

ActionSetting
Non-persisted action / navigation row for search and jump targets.
ActionSettingsTile
Action tile for triggering operations.
AnimatedSettingText
Animated text that smoothly transitions between values.
AnimatedSettingValue
Animated wrapper for setting values that provides visual feedback on changes.
AppSnackbar
Modern snackbar helper with Material Design 3 styling.
BoolSetting
Boolean setting definition.
CardSettingsSection
Card-based settings section with custom styling.
ColorSetting
Color setting definition (stored as int ARGB value).
ColorSettingsTile
Color picker tile.
DoubleSetting
Double/float setting definition.
EasyLocalizationAdapter
Deprecated: Use EasyLocalizationAdapterImpl from package:flutter_settings_framework/src/localization/easy_localization_adapter.dart instead. This stub does not actually use easy_localization — its translate method simply returns the key unchanged.
EasyLocalizationAdapterImpl
Localization provider that integrates with easy_localization.
EmptySearchResults
Empty search results widget.
EnumSetting
Enum-like setting using string values with predefined options.
EnumSettingsTile
Enum setting tile with support for inline or modal editing.
InfoSettingsTile
Info tile for displaying read-only information.
InlineEnumChips
Inline enum chips for >4 options.
InlineEnumSelector
Inline enum selector using SegmentedButton for <=4 options.
InlineIntStepper
Inline stepper widget for integer values.
IntSetting
Integer setting definition.
IntSettingsTile
Integer setting tile with support for inline or modal editing.
LocalizationProvider
Localization provider interface.
MapLocalizationProvider
Deprecated: Use PreIndexedLocalizationProvider from package:flutter_settings_framework/src/localization/easy_localization_adapter.dart instead, which provides the same functionality with a clearer name.
MemoryStorage
In-memory storage implementation for testing.
Navigation tile that opens another screen/page.
PreIndexedLocalizationProvider
Pre-indexed localization provider.
ProfileActionTile
Profile action row. destructive uses the error color.
ProfileBudgetCard
Inner budget column: title, caption, limit, spent, optional progress bar.
ProfileChip
One chip in ProfileChipRow.
ProfileChipRow
Horizontal wrap of selectable status / filter chips.
ProfileCopyRow
Label + value row with a trailing copy action. Host owns clipboard.
ProfileHeroMetric
Large metric panel (caption, optional status, value, optional footnote).
ProfileKpiItem
One chip in ProfileKpiStrip.
ProfileKpiStrip
Horizontal strip of compact KPI chips.
ProfileLinkedAccountTile
Sign-in method row. Host supplies connected / disconnected status.
ProfileNotificationGroup
Grouped notification chrome: ExpansionTile plus optional footer action.
ProfileNotificationTile
Single notification row. title / subtitle are host widgets so user-generated copy can keep its own text direction.
ProfilePlaceholder
Compact centered empty, error, or loading state.
ProfilePlanCard
Plan / membership summary panel.
ProfileSectionHeader
Padded section title with an optional trailing action.
ProfileSecurityTile
Security status row. ok colors the trailing icon success vs warning.
ProfileSessionTile
Device / session row. Host supplies the current-device badge.
ProfileSettingsAction
Trailing icon action for ProfileSettingsCard.
ProfileSettingsCard
Host-filled account row: avatar slot, title/subtitle, flush trailing actions.
ProfileStatGrid
Two-column grid of compact stats.
ProfileStatItem
One cell in ProfileStatGrid.
ProfileStatusBanner
Filled status panel with optional message and action.
ProfileTimelineTile
Compact activity row. Not an unread notification style.
RegistrySettingsPage
Convention-based settings page that builds UI from a SettingsRegistry.
RegistrySettingsPageState
State API for host-owned navigation integrations.
ResponsiveLayout
Responsive layout helper.
SearchIndex
Multi-language search index for settings.
SearchResult
Search result containing a setting and its match score.
SelectSettingsTile<T>
Selection tile with dialog picker.
SettingAnchor
Wraps a setting tile with a GlobalKey and optional highlight decoration.
SettingAnchorRegistry
Registry of GlobalKeys for setting tiles, used to scroll and highlight.
SettingChangeEvent<T>
Event emitted when a setting value changes.
SettingDefinition<T>
Base class for all setting definitions.
SettingNotifier<T>
Notifier for a single setting value.
SettingsCollapsibleSubsection
A settings group inside a section that starts closed and grows downward.
SettingsController
Stream/callback-based controller for settings management.
SettingsDialog
Responsive dialog helper.
SettingSection
Section definition for grouping settings.
SettingsLtr
Isolates Latin codes, hex, versions, and numerals from ambient RTL.
SettingsPageScaffold
Settings page scaffold with search and sections.
SettingsProviderFactory
Helper class for bulk provider creation.
SettingsProviders
Settings providers container.
SettingsRegistry
Registry for all setting definitions.
SettingsSearchBar
SettingsSectionList
A bounded settings catalog whose section anchors are always measurable.
SettingsSectionNavigation
Coordinates section jumps while expandable settings finish laying out.
SettingsSectionWidget
Collapsible settings section.
SettingsStorage
Abstract interface for settings storage.
SettingsSubsectionHeader
Sub-section header within a settings section.
SettingsTile
Base settings tile widget.
SharedPreferencesStorage
Storage implementation using SharedPreferences.
SliderSettingsTile
Slider tile for numeric settings.
SplitScreenLayout
Split-screen layout for settings.
StringListSetting
String list setting definition.
StringSetting
String setting definition.
SwitchSettingsTile
Switch tile for boolean settings.

Enums

ProfileBannerTone
Color treatment for ProfileStatusBanner.
ProfileBudgetAttention
Visual treatment for a budget that is on track, near, or over the limit.
ProfileHeroTone
Color treatment for ProfileHeroMetric status and value.
ProfilePlaceholderKind
Visual kind for ProfilePlaceholder.
ScreenSize
Screen size breakpoints.
SettingEditMode
Edit mode for settings - determines how the setting value is changed.
SettingsSearchBarMode
Search bar for settings. Visual mode for SettingsSearchBar.
SettingType
The type of a setting value for serialization purposes.
SnackbarType
Snackbar type for different visual styles.

Extensions

SettingsRefExtension on WidgetRef
Extension methods for convenient access to settings in widgets.

Properties

settingsControllerProvider → Provider<SettingsController>
Provider for the settings controller.
final
settingsProvidersProvider → Provider<SettingsProviders>
Provider for the settings providers container.
final
settingsSearchIndexProvider → Provider<SearchIndex>
Provider for the search index.
final
settingsSearchResultsProvider → ProviderFamily<List<SearchResult>, String>
Built-in provider for search results by query.
final

Functions

buildSearchResultWidgets(List<SearchResult> results, {required Widget tileBuilder(SettingDefinition setting), required String sectionTitleBuilder(String sectionKey), String settingTitleBuilder(SettingDefinition setting)?, void onResultSelected(SearchResult result)?, bool showBreadcrumbSubtitle = true}) → List<Widget>
Build settings widgets from search results.
createAutoDisposeSettingProvider<T>(SettingDefinition<T> setting, SettingsController getController()) → NotifierProvider<SettingNotifier<T>, T>
Deprecated: This function does not provide actual auto-dispose behavior — it simply delegates to createSettingProvider.
createSearchProvider(SearchIndex searchIndex, String query) → Provider<List<SearchResult>>
Provider for search results (legacy; prefer settingsSearchResultsProvider).
createSettingProvider<T>(SettingDefinition<T> setting, SettingsController getController()) → NotifierProvider<SettingNotifier<T>, T>
Creates a provider for a single setting.
filterWidgetsBySearch(List<Widget> widgets, String query, {String? sectionTitle}) → List<Widget>
Filter widget children based on search query.
initializeSettings({required SettingsRegistry registry, required SettingsStorage storage, LocalizationProvider? localizationProvider}) → Future<SettingsProviders>
Initialize the settings framework for Riverpod.
isSettingEnabled(SettingsProviders settings, SettingDefinition setting, WidgetRef ref) → bool
Whether a setting is enabled based on its SettingDefinition.dependsOn and SettingDefinition.enabledWhen. Use when building tiles so dependent settings are disabled until the dependency is met.
normalizeSearchText(String input) → String
Fold case and Arabic presentation so search matches across scripts.
scrollToSetting(SettingAnchorRegistry registry, String settingKey, {ScrollController? controller, double? knownOffset, double alignment = 0.1}) → Future<void>
Convenience: scroll using a SettingAnchorRegistry.
settingsBreadcrumb(String section, String title, TextDirection direction) → String
Section › title in LTR, section ‹ title in RTL.
settingsChevronEnd(BuildContext context, {Color? color, double? size}) → Icon
End-pointing chevron (forward / open).
settingsEmptySearchFallback(String query, TextDirection direction) → String
Package fallback empty-search copy with locale-appropriate quotes.
settingsMaterialColorName(BuildContext context, MaterialColor color) → String
Material palette name for color-picker rows.
settingsUndoLabel(BuildContext context) → String
Undo chrome when the host does not pass AppSnackbar.undo a label.

Typedefs

SettingChangeCallback<T> = void Function(SettingDefinition<T> setting, T oldValue, T newValue)
Callback type for setting change notifications.
SettingFormatter<T> = String Function(T value, BuildContext context)
Formatter function type for displaying setting values.
SettingProvider<T> = NotifierProvider<SettingNotifier<T>, T>
Type alias for a setting provider.
SettingValidator<T> = bool Function(T value)
Validator function type for setting values.

Exceptions / Errors

SettingNotFoundError
Error thrown when a setting is not found in the registry.