Skip to main content

Documentation Index

Fetch the complete documentation index at: https://synapsync.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

NbxTextFieldWidget is a text input component designed for standalone use cases that don’t require Form integration. It’s ideal for search fields, filters, or simple inputs that manage their own state via onChanged callbacks. For Form-integrated validation, use NbxTextFormFieldWidget instead.

​
Basic Usage

NbxTextFieldWidget(
  NbxInputParameters(
    controller: myController,
    isRequired: false,
    inputType: NbxInputType.text,
    labelText: 'Search',
    hintText: 'Enter search term',
    onChanged: (value) => print('Changed: $value'),
  ),
)

​
Widget Properties

​
inputParameters
NbxInputParameters
required
The configuration parameters for this text field. All customization is done through this parameter object.

​
NbxInputParameters

Immutable configuration object that groups all parameters needed by text input widgets.

​
Required Parameters

​
isRequired
bool
required
Whether the field is required. If true, requiredErrorMessage must also be provided.
​
inputType
NbxInputType
required
The logical type of the input field, determines keyboard type, input formatters, and validation behavior.

​
Text Labels

​
hintText
String?
Placeholder text shown when the field is empty. Either hintText or labelText must be provided.
​
labelText
String?
Label text for the input field. Either hintText or labelText must be provided.
​
helperText
String?
Supporting text displayed below the input field.

​
Input Behavior

​
obscureText
bool
default:"false"
Whether to obscure the text (for password fields).
​
isReadOnly
bool
default:"false"
Whether the field is read-only.
​
isEnabled
bool
default:"true"
Whether the field is enabled.
​
autoDisposeController
bool
default:"true"
Whether to automatically dispose the controller when the widget is disposed.

​
Input Constraints

​
minLines
int?
Minimum number of lines for the input field.
​
maxLines
int?
default:"1"
Maximum number of lines for the input field.
​
maxLength
int?
Maximum number of characters allowed.

​
Validation

​
requiredErrorMessage
String?
Error message to display when required field is empty. Required if isRequired is true.
​
validator
String? Function(String? value)?
Pure validator function that receives input value and returns error message or null.
​
onValidationResult
void Function(String? errorMessage)?
Notification callback called with the final error post-validation (null means valid).
​
autovalidateMode
AutovalidateMode
default:"AutovalidateMode.onUserInteraction"
When to trigger validation automatically.
​
showErrorText
bool
default:"true"
Whether to show error text below the input field.

​
Styling and Decoration

​
decorationStyle
NbxInputDecorationStyle
default:"NbxInputDecorationStyle.outlined"
Visual style of the input field decoration.
​
inputState
NbxInputState
default:"NbxInputState.neutral"
Visual state of the input field (neutral, success, error).
​
suffixIcon
Widget?
Custom suffix widget - takes priority over suffixIconType.
​
prefixIcon
Widget?
Widget displayed at the start of the input field.
​
suffixIconType
NbxSuffixIconType
default:"NbxSuffixIconType.none"
Automatic suffix icon type. Ignored when suffixIcon is provided.
​
fillColor
Color?
Background fill color for the input field.
​
floatingLabelBehavior
FloatingLabelBehavior?
How the label should behave when the field gains focus.

​
Border Customization

​
border
InputBorder?
Default border for the input field.
​
enabledBorder
InputBorder?
Border when the field is enabled.
​
focusedBorder
InputBorder?
Border when the field has focus.
​
errorBorder
InputBorder?
Border when the field has an error.
​
focusedErrorBorder
InputBorder?
Border when the field has an error and focus.
​
disabledBorder
InputBorder?
Border when the field is disabled.

​
Callbacks

​
onChanged
ValueChanged<String>?
Called whenever the text changes.
​
onSubmitted
ValueChanged<String>?
Called when the user submits the field.
​
onTap
void Function()?
Called when the input field is tapped.
​
suffixOnPressed
VoidCallback?
Called when the suffix icon is pressed.

​
Other Properties

​
controller
TextEditingController?
Controller for the text input. If not provided, one will be created automatically.
​
textInputAction
TextInputAction?
The type of action button to use for the keyboard.
​
inputFormatters
List<TextInputFormatter>?
Input formatters to apply to the text.
​
showCharacterCounter
bool
default:"false"
Whether to show a character counter when maxLength is set.

​
NbxInputType Enum

Defines the logical type of input field:
  • NbxInputType.text - General text input
  • NbxInputType.free - Free-form input with no validation
  • NbxInputType.onlyText - Alphabetic characters only
  • NbxInputType.textAndNumbers - Alphanumeric characters
  • NbxInputType.dropdownMenu - Read-only dropdown-style input
  • NbxInputType.alphabet - Alphabetic characters with spaces
  • NbxInputType.number - Numeric input
  • NbxInputType.phone - Phone number input
  • NbxInputType.password - Password input (obscured by default)
  • NbxInputType.decimalNumber - Decimal number input
  • NbxInputType.email - Email address input

​
NbxInputDecorationStyle Enum

Defines the visual appearance of the input field:
  • NbxInputDecorationStyle.floating - Label appears inside and floats above when focused
  • NbxInputDecorationStyle.outlined - Label appears above the input field
  • NbxInputDecorationStyle.filled - Only hint text is shown, no label

​
NbxSuffixIconType Enum

Automatic suffix icon types:
  • NbxSuffixIconType.none - No automatic suffix icon
  • NbxSuffixIconType.eye - Toggles password visibility
  • NbxSuffixIconType.cancel - Clears the input field content

​
NbxInputState Enum

Visual state of the input field:
  • NbxInputState.neutral - Default state with no indicators
  • NbxInputState.success - Valid field with success border
  • NbxInputState.error - Field has errors

​
Examples

​
Basic Text Field

NbxTextFieldWidget(
  NbxInputParameters(
    isRequired: false,
    inputType: NbxInputType.text,
    labelText: 'Username',
    hintText: 'Enter your username',
  ),
)

​
Search Field

NbxTextFieldWidget(
  NbxInputParameters(
    isRequired: false,
    inputType: NbxInputType.text,
    hintText: 'Search...',
    prefixIcon: Icon(Icons.search),
    onChanged: (value) => _performSearch(value),
  ),
)

​
Email Input

NbxTextFieldWidget(
  NbxInputParameters(
    isRequired: true,
    inputType: NbxInputType.email,
    labelText: 'Email',
    hintText: 'your.email@example.com',
    requiredErrorMessage: 'Email is required',
  ),
)

​
Password Field

NbxTextFieldWidget(
  NbxInputParameters(
    isRequired: true,
    inputType: NbxInputType.password,
    labelText: 'Password',
    obscureText: true,
    suffixIconType: NbxSuffixIconType.eye,
    requiredErrorMessage: 'Password is required',
  ),
)

​
Multiline Text Area

NbxTextFieldWidget(
  NbxInputParameters(
    isRequired: false,
    inputType: NbxInputType.text,
    labelText: 'Description',
    hintText: 'Enter description',
    minLines: 3,
    maxLines: 5,
  ),
)

​
See Also