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 LayoutMetrics
- 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.
DefaultPainter also implements LayoutMetrics, providing the default spatial values used when a painter does not implement that interface.
func (DefaultPainter) ContentPadding ¶ added in v0.1.37
func (DefaultPainter) ContentPadding() (float32, float32)
ContentPadding returns the default horizontal and vertical padding.
func (DefaultPainter) PaintTextField ¶
func (p DefaultPainter) PaintTextField(canvas widget.Canvas, st *PaintState)
PaintTextField renders a minimal text field with gray outline. It uses the pre-computed fields from PaintState for cursor/selection positioning.
func (DefaultPainter) TextFieldCornerRadius ¶ added in v0.1.37
func (DefaultPainter) TextFieldCornerRadius() float32
TextFieldCornerRadius returns the default corner radius.
func (DefaultPainter) TextFieldCursorWidth ¶ added in v0.1.37
func (DefaultPainter) TextFieldCursorWidth() float32
TextFieldCursorWidth returns the default cursor width.
func (DefaultPainter) TextFieldFontSize ¶ added in v0.1.37
func (DefaultPainter) TextFieldFontSize() float32
TextFieldFontSize returns the default font size.
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 LayoutMetrics ¶ added in v0.1.37
type LayoutMetrics interface {
// ContentPadding returns horizontal and vertical padding inside the text field.
ContentPadding() (horizontal, vertical float32)
// TextFieldFontSize returns the font size for the text content.
TextFieldFontSize() float32
// TextFieldCursorWidth returns the cursor line width in pixels.
TextFieldCursorWidth() float32
// TextFieldCornerRadius returns the corner radius for the text field border.
TextFieldCornerRadius() float32
}
LayoutMetrics allows theme painters to provide spatial metrics used by the widget to compute pre-computed PaintState fields (ContentRect, CursorRect, etc.).
Painters that implement this interface provide custom padding, font size, etc. Painters that do not implement it get default values from DefaultPainter.
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 {
// Legacy fields (kept for backward compatibility).
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
// DisplayText is the text to render, already masked if password.
DisplayText string
// ContentRect is the inner text area (bounds minus theme padding).
ContentRect geometry.Rect
// CursorRect is the cursor line rectangle (zero if no cursor).
CursorRect geometry.Rect
// SelectionRect is the selection highlight rectangle (zero if no selection).
SelectionRect geometry.Rect
// ShowCursor is true when the cursor should be drawn (focused, no selection, enabled).
ShowCursor bool
// ShowSelection is true when a selection highlight should be drawn.
ShowSelection bool
// FontSize is the font size to use for text rendering.
FontSize float32
// ColorScheme provides theme-derived colors. Zero value means use built-in defaults.
ColorScheme TextFieldColorScheme
}
PaintState provides the current text field state to the painter.
Pre-computed geometry fields (DisplayText, ContentRect, CursorRect, SelectionRect) are calculated by the widget using LayoutMetrics from the painter. Painters should use these fields for positioning rather than computing their own cursor/selection coordinates.
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