Tag Input - FUIInputTags

The FUIInputTags is an input box that transforms text values into bubble-like or square-like tags upon detecting a delimiter character.

The FUIInputTags widget classes could be found in:

lib/focus_ui_kit/components/input/fui_input_tags.dart

The FUIInputTags class is the theme class holds the default theme variables/values.

Accessing the theme

To access the theme class object, do the following:

@override
Widget build(BuildContext context) {
    FUIInputTheme fuiInputTheme = context.theme.fuiInput;
    
    // ...
}

Usage

A typical usage of the FUIInputTags would be as follows:

FUIInputTags(
  label: 'Tag Input',
  hint: 'Type something follow by \',\'',
  initialTags: [
    'First',
    'Second',
  ],
  onChanged: (val) {
    // The val is the current string value that has entered
    // including the delimiter (not the tag values).
    print('value: $val');
  },
);

Changing the delimiter/separator

To modify the delimiter or separator, specify a desired list of characters that will serve as delimiters by utilizing the tagSeparators parameter.

FUIInputTags(
  label: 'Tag Input',
  hint: 'Type something follow by \',\'',
  tagSeparators: [';' '.'], // Having ';' and '.' as delimiter.
);

Changing the shape of the tag

To alter the shape of the tag bubble, the fuiInputTagShape parameter can be utilized. This parameter accepts an FUIInputTagShape enum value.

// Square tag shape
FUIInputTags(
  label: 'Tag Input',
  hint: 'Type something follow by \',\'',
  fuiInputTagShape: FUIInputTagShape.square,
);

// Rounded tag shape
FUIInputTags(
  label: 'Tag Input',
  hint: 'Type something follow by \',\'',
  fuiInputTagShape: FUIInputTagShape.rounded,
);

Prefix and Postfix string for tag

If a prefix or a postfix string is desired to be displayed as part of the tag value, this can be accomplished by configuring the tagPrefixString and tagPostfixString parameters.

FUIInputTags(
  label: 'Tag Input',
  hint: 'Type something follow by \',\'',
  tagPrefixString: '#',     // Having '#' character at the front of the tag value
  tagPostfixString: ';',    // Having ';' character at the back of the tag value
);

Obtaining the tag values

The onChanged method property will only return the current text in the input box, including the delimiter. To obtain the tag values in a list, the StringTagController must be utilized.

// Define the StringTagController
StringTagController strTagCtrl = StringTagController();

// Assign the strTagCtrl to the FUIInputTags widget
FUIInputTags(
  stringTagController: strTagCtrl,
  label: 'Tag Input',
  hint: 'Type something follow by \',\'',
);

// To get the values of the tags
if (strTagCtrl.getTags != null && strTagCtrl.getTags!.isNotEmpty) {

    for (var tag in strTagCtrl.getTags!) {
      // Do something...
    }
}

Validation

A pre-validation of tag value can be achieved by implementing the tagStringValidator function.

For instance, the tag value should NOT contain any numbers.

FUIInputTags(
  label: 'No Numbers',
  hint: 'Type something follow by \',\'',
  tagStringValidator: (val) {
    final numbersRegExp = RegExp(r'^[0-9]*$');

    // If detected, return a message.
    return (numbersRegExp.hasMatch(val)) ? 'No numbers allowed' : null;
  },
);

Parameters

Parameters	Description
StringTagController? stringTagController	The controller for the currently available tags.
Validator\<String\>? tagStringValidator	To validate is a give text value should be added as a legit tag. The return data - Null: all good. A string text message: error.
List\<String\>? initialTags	The list of initial tags.
List\<String\> tagSeparators	The list of tag separators / delimiters.
String? tagPrefixString	The prefix string to be included to the tag value.
String? tagPostfixString	The postfix string to be included to the tag value.
TextStyle? tagTextStyle	Overrides the text style for the tag display text.
Color? tagBackgroundColor	The background color for the tag box/bubble.
FUIInputTagShape fuiInputTagShape	The shape of the tag - square or rounded.
FUIColorScheme fuiColorScheme	The color scheme for the `FUIInputTags`.
FUIInputFieldController? fuiInputFieldController	The controller for the input field.
String? label	The input field label within the box.
String? hint	The subtle hint text on the input field.
bool mandatory	Toggle the display of mandatory indicator.
Widget? mandatoryIndicator	A custom mandatory indicator (if needed).
bool showTopLabelBar	Toggle the display of the top label.
String? initialValue	The initial value (or assign it via textEditingController).
FUIInputSize fuiInputSize	The size of the input box, accepts values from `FUIInputSize` enum.
FUIInputStatusType fuiInputStatusType	The status type of the input box.
String? fuiInputStatusText	The status type text (if any).
Widget? sideIcon	The decorative side icon (if any).
FUIInputSideIconPosition fuiInputSideIconPosition	The position of the side icon.
Color? sideIconBackgroundColor	The background color of the side icon portion.

27 March 2025

Focus Theme UI Kit Documentation Help