BankPeriodSelector class

Prev/next time-period navigator for statements, insights and budgets.

Renders a back chevron, the period label, and a forward chevron as one content-sized cluster. Hosts keep the current period in their own state and receive the previous/next period through onChanged: the widget itself is stateless with respect to the selected period (controlled component).

Typical placement is as the header above a spending breakdown chart or a budget gauge, so users can page through months, quarters or years.

Behaviour:

  • The row sizes to its content and centres itself in whatever width it is given. Stretching the label to fill the line pushes the chevrons to opposite screen edges, which turns one control into two unrelated ones with ~140 px of dead space between them and the thing they operate on.
  • The label is formatted per unit (March 2026 / Q1 2026 / 2026) and digits follow the ambient NumeralStyle from BankUiScope (Eastern Arabic-Indic digits in Arabic-script locales).
  • Each chevron is a BankTokens.minTapTarget-square tinted disc — a target you can see and hit — and dims to the theme's disabled opacity, stopping at the minPeriod / maxPeriod bounds (compared at unit granularity).
  • Chevrons flip for right-to-left locales, and their semantic labels stay direction-agnostic ("Previous month" / "Next month").
  • The label crossfades over 150 ms with a short horizontal slide that matches the direction of travel (reversed in RTL); the animation is skipped when the platform requests reduced motion.
  • onTapLabel lets hosts open a month-grid or year picker when the user taps the label itself.
BankPeriodSelector(
  period: DateTime(2026, 3),
  unit: BankPeriodUnit.month,
  onChanged: (next) => setState(() => _period = next),
  minPeriod: DateTime(2024, 1),
  maxPeriod: DateTime.now(),
  onTapLabel: _openMonthGridPicker,
)
Inheritance

Constructors

BankPeriodSelector({required DateTime period, required BankPeriodUnit unit, required ValueChanged<DateTime> onChanged, Key? key, DateTime? minPeriod, DateTime? maxPeriod, VoidCallback? onTapLabel, String? previousSemanticLabel, String? nextSemanticLabel, String labelFormatter(DateTime period)?, TextStyle? labelStyle, IconData? previousIcon, IconData? nextIcon, Color? foregroundColor, Color? chevronBackgroundColor, Duration? animationDuration, Curve? animationCurve})
const

Properties

animationCurve → Curve?
Overrides BankTokens.curveStandard for the label transition.
final
animationDuration → Duration?
Overrides BankTokens.durationFast for the label transition.
final
chevronBackgroundColor → Color?
Overrides the resting fill of the chevron discs. Defaults to the glyph colour at BankTokens.alphaSubtle, which reads as a target on any brand surface in either brightness. Pass Colors.transparent for the old bare-glyph look.
final
foregroundColor → Color?
Overrides BankThemeData.onSurface as the chevron glyph colour (the disabled state keeps the theme's disabled-opacity treatment).
final
hashCode → int
The hash code for this object.
no setterinherited
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
labelFormatter → String Function(DateTime period)?
Replaces the default label text for a normalised period start. Defaults to March 2026 / Q1 2026 / 2026 formatting with ambient-numeral conversion; the returned string is shown verbatim.
final
labelStyle → TextStyle?
Merged over the computed label style (default: BankTokens.headlineSmall in BankThemeData.onSurface).
final
maxPeriod → DateTime?
Latest reachable period (inclusive), compared at unit granularity. The forward chevron disables once period reaches this bound.
final
minPeriod → DateTime?
Earliest reachable period (inclusive), compared at unit granularity. The back chevron disables once period reaches this bound.
final
nextIcon → IconData?
Overrides the forward chevron glyph (default: a direction-aware Icons.chevron_right, mirrored in RTL). Overrides are not mirrored.
final
nextSemanticLabel → String?
Semantic label for the forward chevron. Defaults to an English label matching unit, e.g. Next month.
final
onChanged → ValueChanged<DateTime>
Called with the start of the previous/next period when a chevron is tapped. The host owns the state and rebuilds with the new period.
final
onTapLabel → VoidCallback?
Called when the user taps the period label: hosts typically open a month-grid or year picker here. When null the label is not tappable.
final
period → DateTime
The currently selected period. Any DateTime inside the period is accepted; it is normalised to the start of the unit internally.
final
previousIcon → IconData?
Overrides the back chevron glyph (default: a direction-aware Icons.chevron_left, mirrored in RTL). Overrides are not mirrored.
final
previousSemanticLabel → String?
Semantic label for the back chevron. Defaults to an English label matching unit, e.g. Previous month.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
unit → BankPeriodUnit
Granularity of navigation: month, quarter or year.
final

Methods

createElement() → StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<BankPeriodSelector>
Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String
Returns a one-line detailed description of the object.
inherited
toStringShort() → String
A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited