Documentation
¶
Overview ¶
Package textfield provides a full-featured text input widget.
Construction uses functional options for immutable configuration, while fluent methods handle mutable styling:
field := textfield.New(
textfield.Placeholder("Enter your email"),
textfield.OnChange(handleChange),
textfield.InputType(textfield.TypeEmail),
textfield.MaxLength(255),
).Padding(12)
Visual Style ¶
The visual rendering is provided by a Painter implementation. Each design system (Material 3, Fluent, Cupertino) supplies its own painter to render text fields in the appropriate visual style.
If no painter is set, DefaultPainter is used, which draws a minimal outlined text field suitable for testing and prototyping.
Input Types ¶
Text fields support multiple input types:
- TypeText -- general-purpose text input (default)
- TypePassword -- masked input that shows dots instead of characters
- TypeEmail -- email address input
- TypeNumber -- numeric input
- TypeSearch -- search input
Text Editing ¶
Text fields support standard editing operations:
- Character insertion and deletion at cursor position
- Arrow key movement (Left/Right) with Ctrl for word-level jumps
- Home/End to move to line start/end
- Backspace and Delete for character removal
- Shift+arrows for text selection
- Ctrl+A to select all text
- Ctrl+C/X/V for clipboard copy/cut/paste (placeholder implementation)
Validation ¶
A ValidationFunc can be provided to validate the text field's value. When validation fails, the text field displays an error state with an optional error message. Validation runs on every text change.
Signal Binding ¶
Use ValueSignal to bind the text field to a reactive signal for two-way data binding:
email := state.NewSignal("")
field := textfield.New(textfield.ValueSignal(email))
// email.Get() always reflects the current text field value
Focus ¶
Text fields implement widget.Focusable and participate in tab navigation. When focused, the cursor blinks and the border color changes to indicate the active input state.
Index ¶
- type DefaultPainter
- type InputType
- type Option
- func A11yLabel(label string) Option
- func Disabled(d bool) Option
- func DisabledFn(fn func() bool) Option
- func InitialValue(s string) Option
- func InputTypeOpt(t InputType) Option
- func MaxLength(n int) Option
- func OnChange(fn func(string)) Option
- func OnSubmit(fn func(string)) Option
- func PainterOpt(p Painter) Option
- func Placeholder(s string) Option
- func Validation(fns ...ValidationFunc) Option
- func Value(sig state.Signal[string]) Optiondeprecated
- func ValueSignal(sig state.Signal[string]) Option
- type PaintState
- type Painter
- type TextFieldColorScheme
- type ValidationFunc
- type Widget
- func (w *Widget) AccessibleLabel() string
- func (w *Widget) AccessibleRole() a11y.Role
- func (w *Widget) AccessibleValue() string
- func (w *Widget) Children() []widget.Widget
- func (w *Widget) CursorPosition() int
- func (w *Widget) Draw(_ widget.Context, canvas widget.Canvas)
- func (w *Widget) ErrorMessage() string
- func (w *Widget) Event(ctx widget.Context, e event.Event) bool
- func (w *Widget) HasError() bool
- func (w *Widget) IsFocusable() bool
- func (w *Widget) Layout(_ widget.Context, constraints geometry.Constraints) geometry.Size
- func (w *Widget) Mount(ctx widget.Context)
- func (w *Widget) Padding(v float32) *Widget
- func (w *Widget) Selection() (int, int)
- func (w *Widget) SetText(text string)
- func (w *Widget) Text() string
- func (w *Widget) Unmount()
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DefaultPainter ¶
type DefaultPainter struct{}
DefaultPainter provides a minimal fallback painter with no design system styling. It draws a simple outlined text field suitable for testing and prototyping.
func (DefaultPainter) PaintTextField ¶
func (p DefaultPainter) PaintTextField(canvas widget.Canvas, st PaintState)
PaintTextField renders a minimal text field with gray outline. If the state has a non-zero ColorScheme (via the M3 painter), use those colors.
type InputType ¶
type InputType uint8
InputType represents the type of text input. It determines input behavior such as masking and keyboard hints.
const ( // TypeText is general-purpose text input (default). TypeText InputType = iota // TypePassword masks input characters with dots. TypePassword // TypeEmail is for email address input. TypeEmail // TypeNumber is for numeric input. TypeNumber // TypeSearch is for search input. TypeSearch )
Input type constants.
type Option ¶
type Option func(*config)
Option configures a text field during construction.
func A11yLabel ¶
A11yLabel sets the accessibility label for the text field. This is announced by screen readers to describe the field's purpose.
func Disabled ¶
Disabled sets the text field's disabled state. A disabled text field does not respond to user input and is drawn with a dimmed appearance.
func DisabledFn ¶
DisabledFn sets a dynamic function that is evaluated to determine whether the text field is disabled. When set, this takes precedence over the static value.
func InitialValue ¶
InitialValue sets the initial text value for the field.
func InputTypeOpt ¶
InputTypeOpt sets the input type (text, password, email, number, search).
func MaxLength ¶
MaxLength sets the maximum number of characters allowed. A value of 0 means no limit.
func OnChange ¶
OnChange sets the callback invoked when the text value changes. The callback receives the new text value.
func OnSubmit ¶
OnSubmit sets the callback invoked when the user presses Enter in a single-line text field. The callback receives the current text value.
func PainterOpt ¶
PainterOpt sets the painter used to render the text field. Each design system provides its own painter. If not set, DefaultPainter is used.
func Placeholder ¶
Placeholder sets the placeholder text shown when the field is empty and unfocused.
func Validation ¶
func Validation(fns ...ValidationFunc) Option
Validation sets one or more validation functions. Each function receives the current value and returns an error message (empty string means valid). Validation runs on every text change.
type PaintState ¶
type PaintState struct {
Text string
Placeholder string
Focused bool
Hovered bool
Disabled bool
HasError bool
ErrorMsg string
CursorPos int
SelectStart int
SelectEnd int
InputType InputType
Bounds geometry.Rect
}
PaintState provides the current text field state to the painter.
type Painter ¶
type Painter interface {
PaintTextField(canvas widget.Canvas, state PaintState)
}
Painter draws the visual representation of a text field. Each design system (Material 3, Fluent, Cupertino) provides its own Painter implementation to render the text field in its visual style.
If no Painter is set, the text field uses DefaultPainter.
type TextFieldColorScheme ¶
type TextFieldColorScheme struct {
Background widget.Color
Border widget.Color
FocusBorder widget.Color
ErrorBorder widget.Color
TextColor widget.Color
Placeholder widget.Color
CursorColor widget.Color
DisabledBg widget.Color
DisabledFg widget.Color
SelectionBg widget.Color
ErrorText widget.Color
}
TextFieldColorScheme provides theme-derived colors for text field painting. Zero value means the painter should use its built-in defaults.
type ValidationFunc ¶
ValidationFunc validates the text field value and returns an error message. An empty string means the value is valid.
type Widget ¶
type Widget struct {
widget.WidgetBase
// contains filtered or unexported fields
}
Widget implements a full-featured text input field with validation, selection, and accessibility support.
A text field is created with New using functional options:
field := textfield.New(
textfield.Placeholder("Enter email"),
textfield.OnChange(handleChange),
textfield.InputType(textfield.TypeEmail),
textfield.MaxLength(255),
)
Fluent styling methods may be chained after construction:
field.Padding(12)
func New ¶
New creates a new text field Widget with the given options.
The returned widget is visible, enabled, and focusable by default. Use options to configure placeholder, change handler, input type, etc.
func (*Widget) AccessibleLabel ¶
AccessibleLabel returns the accessibility label for the text field. If an explicit a11y label was set via A11yLabel, it is returned. Otherwise, the placeholder text is used as a fallback label.
func (*Widget) AccessibleRole ¶
AccessibleRole returns the accessibility role for the text field.
func (*Widget) AccessibleValue ¶
AccessibleValue returns the current text value for assistive technology. For password fields, the value is masked.
func (*Widget) CursorPosition ¶
CursorPosition returns the current cursor position as a rune index.
func (*Widget) ErrorMessage ¶
ErrorMessage returns the current validation error message, or empty string if valid.
func (*Widget) IsFocusable ¶
IsFocusable reports whether the text field can currently receive focus. A text field is focusable when it is visible, enabled, and not disabled.
func (*Widget) Layout ¶
Layout calculates the text field's preferred size within the given constraints.
func (*Widget) Mount ¶
Mount creates signal bindings for push-based invalidation. Implements widget.Lifecycle.
func (*Widget) Padding ¶
Padding sets the padding around the text field content. Returns the widget for method chaining.
func (*Widget) Selection ¶
Selection returns the current selection range as (start, end) rune indices. If start == end, there is no selection.
func (*Widget) Unmount ¶
func (w *Widget) Unmount()
Unmount is called when the text field is removed from the widget tree. Implements widget.Lifecycle.
Source Files