Available from v8.0.0
BB.InputText
A SwiftUI view that displays a text input field with customizable appearance and behavior.
Platform availability: iOS 17.0+
When to use:
- Use BB.InputText when collecting general text input from users, such as names, emails, descriptions, or search queries.
- Consider BB.InputAmount for monetary values, BB.InputPassword for sensitive credentials, or BB.InputDate for date selections.
Import
import BackbaseDesignSystem
import SwiftUI
Visual reference
|
Error |
Disabled |
API reference
BB.InputText
BB.InputText is a standardized text input component for SwiftUI applications. It supports various states including editing, focused, and error states, along with optional labels, icons, and helper text.
Initializers
init(text:placeholder:labelPrimaryText:labelSecondaryText:)
Creates a new text input view with the specified binding and optional labels.
|
Parameter |
Type |
Default |
Description |
|---|---|---|---|
|
text |
Binding<String> |
— |
Binding to the input text |
|
placeholder |
String |
— |
Placeholder text when the field is empty |
|
labelPrimaryText |
String? |
nil |
Primary label text above the input |
|
labelSecondaryText |
String? |
nil |
Secondary label text |
Methods
leadingIcon(_:accessibilityLabel:)
Sets an icon to display on the leading side of the text input.
|
Parameter |
Type |
Description |
|---|---|---|
|
image |
Image |
The icon image to display |
|
accessibilityLabel |
String |
Accessibility label for the icon |
Returns: Self - A modified version of the input with the icon.
errorText(_:)
Sets the error text using a binding.
|
Parameter |
Type |
Description |
|---|---|---|
|
text |
Binding<String?> |
Binding to the error message |
Returns: Self - A modified version of the input with error text.
helperText(_:)
Sets the helper text.
|
Parameter |
Type |
Description |
|---|---|---|
|
text |
String? |
Helper text to display below the input |
Returns: Self - A modified version of the input with helper text.
helperText(_:) (Binding)
Sets the helper text using a binding.
|
Parameter |
Type |
Description |
|---|---|---|
|
text |
Binding<String?> |
Binding to the helper text |
Returns: Self - A modified version of the input with helper text.
readOnly(_:)
Sets the read-only state.
|
Parameter |
Type |
Description |
|---|---|---|
|
isReadOnly |
Bool |
Whether the input is read-only |
Returns: Self - A modified version of the input with read-only state.
readOnly(_:) (Binding)
Sets the read-only state using a binding.
|
Parameter |
Type |
Description |
|---|---|---|
|
isReadOnly |
Binding<Bool> |
Binding to the read-only state |
Returns: Self - A modified version of the input with read-only state.
keyboardType(_:)
Sets the keyboard type for the text input.
|
Parameter |
Type |
Description |
|---|---|---|
|
type |
UIKeyboardType |
The keyboard type to use |
Returns: Self - A modified version of the input with the keyboard type.
Configuration
|
Property |
Type |
Default |
|---|---|---|
|
text |
Binding<String> |
— |
|
placeholder |
String |
— |
|
labelPrimaryText |
String? |
nil |
|
labelSecondaryText |
String? |
nil |
text
The text property binds to the string value entered by the user. This is a required parameter for the initializer.
@State private var enteredText: String = ""
BB.InputText(text: $enteredText, placeholder: "Enter text")
placeholder
The placeholder property displays hint text when the input field is empty.
BB.InputText(text: $text, placeholder: "Enter your name")
labelPrimaryText
The labelPrimaryText property displays a primary label above the input field.
BB.InputText(text: $text,
placeholder: "Enter email",
labelPrimaryText: "Email Address")
labelSecondaryText
The labelSecondaryText property displays secondary text next to the primary label.
BB.InputText(text: $text,
placeholder: "Enter email",
labelPrimaryText: "Email",
labelSecondaryText: "(Optional)")
Usage
Basic usage
Create a simple text input field.
import SwiftUI
import BackbaseDesignSystem
@State private var enteredText: String = ""
var body: some View {
BB.InputText(text: $enteredText,
placeholder: "Enter text here")
}
Common use cases
Email input with validation
@State private var emailText: String = ""
@State private var errorMessage: String? = "Invalid email format"
@State private var isReadOnly = false
var body: some View {
BB.InputText(text: $emailText,
placeholder: "Enter email",
labelPrimaryText: "Email",
labelSecondaryText: "We will not share your email")
.leadingIcon(Image(systemName: "envelope"),
accessibilityLabel: "Email icon")
.keyboardType(.emailAddress)
.errorText($errorMessage)
.helperText("Please enter a valid email address")
.readOnly(isReadOnly)
}
Using SwiftUI focus state
enum FocusFields: Hashable {
case field1
case field2
}
@State var disabled: Bool = false
@FocusState var isFocused: FocusFields?
var body: some View {
BB.InputText(
text: $enteredText,
placeholder: "Enter text here"
)
.focused($isFocused, equals: .field1)
.disabled(disabled)
}
States and variants
State priority
The component applies states in the following priority order (highest to lowest):
- Read Only
- Disabled
- Error
- Focused
- Normal
Normal state
The default state when the input is interactive but not focused.
Visual characteristics:
- Default border color
- Placeholder text visible when empty
- Leading icon in support color
Focused state
Active when the input field has keyboard focus.
Visual characteristics:
- Brand-colored border
- Cursor visible in the input field
Error state
Displayed when validation fails or an error message is set.
Visual characteristics:
- Danger-colored border
- Error icon displayed
- Error text shown below the input in danger color
Disabled state
Applied when the input is not interactive.
Visual characteristics:
- Disabled border color
- Disabled text color
- User interaction blocked
Read-only state
Applied when the input displays content but does not accept input.
Visual characteristics:
- Disabled background color
- Disabled border color
- Content is visible but not editable
Customization
Leading icon
Add an icon to the leading side of the input field.
BB.InputText(text: $text, placeholder: "Search")
.leadingIcon(Image(systemName: "magnifyingglass"),
accessibilityLabel: "Search icon")
Helper and error text
Display contextual information or validation errors below the input.
BB.InputText(text: $text, placeholder: "Enter password")
.helperText("Must be at least 8 characters")
.errorText($errorMessage)
Keyboard type
Configure the keyboard type for specific input types.
BB.InputText(text: $phone, placeholder: "Enter phone number")
.keyboardType(.phonePad)
Accessibility
This component can be configured with accessibility features at the integration level. Use the standard SwiftUI accessibility modifiers to ensure a fully accessible experience for all users.
Accessibility configuration
|
Modifier |
Description |
|---|---|
|
.accessibilityLabel(_:) |
Sets the accessibility label for screen readers |
|
.accessibilityHint(_:) |
Provides additional context for the action |
|
.accessibilityValue(_:) |
Sets the current value for the element |
Best practices
- Provide meaningful accessibility labels that describe the element's purpose.
- Use accessibility hints to provide additional context when needed.
- Ensure all interactive elements are accessible.
BB.InputText()
.accessibilityLabel("Descriptive label")
.accessibilityHint("Additional context")
Dependencies
- External dependencies: None
- Internal dependencies: BackbaseDesignSystem
Design tokens
Component styling is applied automatically through the design system's theming infrastructure.
JSON tokens
Tokens are defined in defaultTokens.json, which is integrated in the bundle of the framework, and can be customized by providing your own theme JSON file.
Token groups used by InputText:
- color/input/default: Default state background, border, placeholder, and value colors
- color/input/focused: Focused state border color
- color/input/error: Error state border and helper text colors
- color/input/disabled: Disabled state colors
- color/input/read-only: Read-only state colors
Default state tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Border |
theme.color.input.default.border |
{theme.color.border.default} |
|
Placeholder |
theme.color.input.default.placeholder |
{theme.color.foreground.support} |
|
Value |
theme.color.input.default.value |
{theme.color.foreground.default} |
|
Icon |
theme.color.input.default.icon |
{theme.color.foreground.support} |
Focused state tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Border |
theme.color.input.focused.border |
{theme.color.border.brand} |
Error state tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Border |
theme.color.input.error.border |
{theme.color.border.danger} |
|
Helper Text |
theme.color.input.error.helper-text |
{theme.color.foreground.danger} |
|
Icon |
theme.color.input.error.icon |
{theme.color.foreground.danger} |
Disabled state tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Border |
theme.color.input.disabled.border |
{theme.color.border.disabled} |
|
Value |
theme.color.input.disabled.value |
{theme.color.foreground.disabled} |
Read-only state tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Background |
theme.color.input.read-only.background |
{theme.color.background.disabled} |
|
Border |
theme.color.input.read-only.border |
{theme.color.border.disabled} |
Dimension tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Corner Radius |
theme.radius.input.default |
8 |
|
Height |
theme.height.input.md |
44 |
|
Padding X |
theme.padding-x.input.md |
16 |
|
Padding Y |
theme.padding-y.input.md |
8 |
|
Border Width |
theme.border-width.input.default |
1 |
Semantic tokens
|
Token |
API Reference |
Description |
|---|---|---|
|
Default Border |
Theme.colors.border.default |
Default input border color |
|
Focused Border |
Theme.colors.border.brand |
Border color when focused |
|
Error Border |
Theme.colors.border.danger |
Border color in error state |
|
Disabled Border |
Theme.colors.border.disabled |
Border color when disabled |
|
Placeholder |
Theme.colors.foreground.support |
Placeholder text color |
|
Value |
Theme.colors.foreground.default |
Input value text color |
|
Disabled Value |
Theme.colors.foreground.disabled |
Text color when disabled |
|
Error Text |
Theme.colors.foreground.danger |
Error message text color |
|
Icon |
Theme.colors.foreground.support |
Leading icon color |
Localization
The following strings are available for localization:
|
Key |
Default Value |
Description |
|---|---|---|
|
DesignSystem.inputText.accessibility.textFieldLabel |
"Text input" |
Accessibility label for the input |
|
DesignSystem.inputText.accessibility.errorIcon |
"Error icon" |
Accessibility label for error icon |
|
DesignSystem.inputText.accessibility.clearButton |
"Clear button" |
Accessibility label for clear button |
To customize these strings, add the keys to your app's Localizable.strings file.
See also
- BB.InputPassword - Password input field component
- BB.InputAmount - Amount input field component
- BB.InputDate - Date input field component