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.

​
Text Input Components

Nebux provides form-integrated text input widgets with comprehensive validation and state management.

​
NbxTextFormFieldWidget

A text input widget that integrates with Flutter’s Form system for validation.

​
Basic Usage

import 'package:nebux_design_system/nebux_design_system.dart';

final _formKey = GlobalKey<FormState>();
final _controller = TextEditingController();

Form(
  key: _formKey,
  child: NbxTextFormFieldWidget(
    NbxInputParameters(
      controller: _controller,
      isRequired: true,
      inputType: NbxInputType.text,
      labelText: 'Full Name',
      hintText: 'Enter your full name',
      requiredErrorMessage: 'Name is required',
    ),
  ),
)

​
NbxInputParameters

All input widgets are configured using NbxInputParameters, which provides a comprehensive set of properties:
​
labelText
String?
Label text displayed above or inside the input
​
hintText
String?
Placeholder text shown when input is empty
​
isRequired
bool
required
Whether the field is required (triggers validation)
​
inputType
NbxInputType
required
Type of input: text, email, password, number, etc.
​
controller
TextEditingController?
Controller for managing input value
​
obscureText
bool
default:"false"
Whether to obscure text (for passwords)
​
isReadOnly
bool
default:"false"
Whether the field is read-only
​
isEnabled
bool
default:"true"
Whether the field is enabled
​
maxLines
int?
Maximum number of lines for multi-line inputs
​
maxLength
int?
Maximum character length
​
validator
String? Function(String?)?
Custom validation function
​
onValidationResult
void Function(String?)?
Callback with final validation error (null = valid)
​
onChanged
ValueChanged<String>?
Callback when input value changes
​
suffixIcon
Widget?
Custom suffix icon widget
​
prefixIcon
Widget?
Custom prefix icon widget
​
decorationStyle
NbxInputDecorationStyle
default:"outlined"
Decoration style for the input field
​
inputState
NbxInputState
default:"neutral"
Visual state: neutral, success, or error
​
helperText
String?
Supporting text displayed below the input
​
showCharacterCounter
bool
default:"false"
Whether to show character counter when maxLength is set

​
Input Types

Common input configurations: 
NbxTextFormFieldWidget(
  NbxInputParameters(
    controller: emailController,
    isRequired: true,
    inputType: NbxInputType.email,
    labelText: 'Email',
    hintText: 'Enter your email',
    requiredErrorMessage: 'Email is required',
  ),
)

​
NbxPhoneFieldWidget

A specialized widget that combines country picker and phone number input with automatic validation.

​
Basic Usage

final countryCodeController = TextEditingController();
final phoneController = TextEditingController();
Country? selectedCountry;

NbxPhoneFieldWidget(
  countrySelected: selectedCountry,
  countryCodeInputParameters: NbxCountryPickerParameters(
    controller: countryCodeController,
    isRequired: true,
    inputType: NbxInputType.text,
    labelText: 'Country',
    hintText: 'Select',
    requiredErrorMessage: 'Country is required',
  ),
  phoneNumberInputParameters: NbxInputParameters(
    controller: phoneController,
    isRequired: true,
    inputType: NbxInputType.phone,
    labelText: 'Phone Number',
    hintText: 'Enter phone',
    requiredErrorMessage: 'Phone is required',
  ),
  modal: NbxCountryPickerModalParameters(
    countries: allCountries,
    showPhoneCode: true,
    appBarTitle: 'Select Country',
    onSelect: (country) {
      setState(() {
        selectedCountry = country;
      });
    },
  ),
)

​
Features

  • Automatic validation based on country-specific phone number lengths
  • Phone input is read-only until a country is selected
  • Clears phone number when country changes
  • Validates min/max length based on selected country
The phone field automatically validates the phone number length based on the minLength and maxLength properties of the selected Country object.

​
NbxCountryPickerInput

A read-only input that opens a country picker dialog on tap.

​
Basic Usage

final controller = TextEditingController();

NbxCountryPickerInput(
  inputParameters: NbxCountryPickerParameters(
    controller: controller,
    isRequired: true,
    inputType: NbxInputType.text,
    labelText: 'Country',
    hintText: 'Select country',
    requiredErrorMessage: 'Country is required',
  ),
  modal: NbxCountryPickerModalParameters(
    countries: allCountries,
    showPhoneCode: false,
    appBarTitle: 'Select Country',
    onSelect: (country) {
      controller.text = country.name;
    },
  ),
)

​
NbxCountryPickerModalParameters

Configuration for the country picker modal:
​
countries
List<Country>
required
List of countries to display
​
showPhoneCode
bool
default:"false"
Whether to show phone codes in the list
​
appBarTitle
String
default:"'Select Country'"
Title for the picker modal
​
onSelect
void Function(Country)
required
Callback when a country is selected
​
showSearchBox
bool
default:"true"
Whether to show search functionality

​
Validation Examples

​
Custom Validation

NbxTextFormFieldWidget(
  NbxInputParameters(
    controller: usernameController,
    isRequired: true,
    inputType: NbxInputType.text,
    labelText: 'Username',
    hintText: 'Enter username',
    requiredErrorMessage: 'Username is required',
    validator: (value) {
      if (value == null || value.isEmpty) return null;
      if (value.length < 3) {
        return 'Username must be at least 3 characters';
      }
      if (!RegExp(r'^[a-zA-Z0-9_]+$').hasMatch(value)) {
        return 'Username can only contain letters, numbers, and underscores';
      }
      return null;
    },
  ),
)

​
Validation Result Callback

String? errorMessage;

NbxTextFormFieldWidget(
  NbxInputParameters(
    controller: emailController,
    isRequired: true,
    inputType: NbxInputType.email,
    labelText: 'Email',
    hintText: 'Enter email',
    requiredErrorMessage: 'Email is required',
    onValidationResult: (error) {
      setState(() {
        errorMessage = error;
      });
    },
  ),
)

​
Best Practices

When using isRequired: true, you must provide a requiredErrorMessage. This is enforced by compile-time assertions.
For outlined decoration style, both labelText and hintText must be provided.
Use onValidationResult for reactive UI updates based on validation state, not for implementing validation logic.