Documentation
¶
Overview ¶
Package chip provides a compact chip widget for tags, filters, and inline actions, following the Material 3 chip guidelines.
A chip is a small, interactive, pill-shaped element. It can act as a simple action (assist/suggestion chip) or as a toggleable filter (filter chip).
Construction uses functional options for immutable configuration, while fluent methods handle mutable styling:
c := chip.New(
chip.Label("In stock"),
chip.Selectable(true),
chip.OnSelectedChanged(func(sel bool) { applyFilter(sel) }),
).Padding(2)
Modes ¶
- Action chip (default): clicking invokes the OnClick handler. Use for assist or suggestion chips.
- Filter chip (Selectable is true): clicking toggles the selected state and invokes OnSelectedChanged. The chip renders a filled background when selected and an outlined background when not.
Selection write-back ¶
On activation a selectable chip toggles its selected state and writes the new value back to the appropriate source, matching the checkbox widget:
- With a writable SelectedSignal, the new value is written to the signal (two-way binding).
- With only a static value, the chip updates its own internal state.
- With a read-only source (SelectedFn or SelectedReadonlySignal), the chip leaves the source untouched; the owner is responsible for updating it in response to OnSelectedChanged.
Visual Style ¶
The visual rendering is provided by a Painter implementation. Each design system (Material 3, Fluent, Cupertino) may supply its own painter. If no painter is set, DefaultPainter is used.
Signal Binding ¶
Chip properties can be bound to reactive signals from the state package:
- LabelSignal / LabelReadonlySignal / LabelFn -- the label text
- SelectedSignal / SelectedReadonlySignal / SelectedFn -- selected state
- DisabledSignal / DisabledReadonlySignal / DisabledFn -- disabled state
Accessibility ¶
A chip is focusable when visible, enabled, and not disabled. It activates on the Enter and Space keys, matching the button widget.
Index ¶
- type ChipColorScheme
- type DefaultPainter
- type Option
- func ColorSchemeOpt(cs ChipColorScheme) Option
- func Disabled(d bool) Option
- func DisabledFn(fn func() bool) Option
- func DisabledReadonlySignal(sig state.ReadonlySignal[bool]) Option
- func DisabledSignal(sig state.Signal[bool]) Option
- func Label(s string) Option
- func LabelFn(fn func() string) Option
- func LabelReadonlySignal(sig state.ReadonlySignal[string]) Option
- func LabelSignal(sig state.Signal[string]) Option
- func OnClick(fn func()) Option
- func OnSelectedChanged(fn func(bool)) Option
- func PainterOpt(p Painter) Option
- func Selectable(enabled bool) Option
- func Selected(sel bool) Option
- func SelectedFn(fn func() bool) Option
- func SelectedReadonlySignal(sig state.ReadonlySignal[bool]) Option
- func SelectedSignal(sig state.Signal[bool]) Option
- type PaintState
- type Painter
- type Widget
- func (w *Widget) Children() []widget.Widget
- func (w *Widget) Draw(_ widget.Context, canvas widget.Canvas)
- func (w *Widget) Event(ctx widget.Context, e event.Event) 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) Selected() bool
- func (w *Widget) SetSelected(sel bool)
- func (w *Widget) Unmount()
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ChipColorScheme ¶
type ChipColorScheme struct {
Background widget.Color // unselected fill color
Border widget.Color // unselected outline color
Label widget.Color // unselected label color
SelectedBackground widget.Color // selected fill color
SelectedLabel widget.Color // selected label color
DisabledBackground widget.Color // fill color when disabled
DisabledLabel widget.Color // label color when disabled
}
ChipColorScheme provides theme-derived colors for chip painting. Zero value means the painter should use its built-in defaults.
type DefaultPainter ¶
type DefaultPainter struct{}
DefaultPainter provides a minimal fallback painter with Material-3-flavored styling: an outlined pill when unselected and a filled pill when selected, with a translucent state layer for hover and press.
func (DefaultPainter) PaintChip ¶
func (p DefaultPainter) PaintChip(canvas widget.Canvas, ps PaintState)
PaintChip renders the chip. If state.ColorScheme is non-zero, its colors are used instead of the built-in defaults.
type Option ¶
type Option func(*config)
Option configures a chip during construction.
func ColorSchemeOpt ¶
func ColorSchemeOpt(cs ChipColorScheme) Option
ColorSchemeOpt sets the color scheme for painting, overriding defaults.
func DisabledFn ¶
DisabledFn sets a dynamic function for the disabled state. When set, this takes precedence over the static value but not over a signal set via DisabledSignal.
func DisabledReadonlySignal ¶
func DisabledReadonlySignal(sig state.ReadonlySignal[bool]) Option
DisabledReadonlySignal binds the disabled state to a read-only signal. Takes highest precedence over all other disabled sources.
func DisabledSignal ¶
DisabledSignal binds the disabled state to a reactive signal.
func LabelFn ¶
LabelFn sets a dynamic label function evaluated on each draw. When set, this takes precedence over the static label but not over a signal set via LabelSignal or LabelReadonlySignal.
func LabelReadonlySignal ¶
func LabelReadonlySignal(sig state.ReadonlySignal[string]) Option
LabelReadonlySignal binds the chip's label to a read-only signal. When set, this takes highest precedence over all other label sources.
func LabelSignal ¶
LabelSignal binds the chip's label to a reactive signal. When set, the signal value takes precedence over both LabelFn and Label but not over LabelReadonlySignal.
func OnClick ¶
func OnClick(fn func()) Option
OnClick sets the handler invoked when the chip is activated by click or keyboard. It fires for both action and filter chips.
func OnSelectedChanged ¶
OnSelectedChanged sets the handler invoked when a selectable chip toggles. The argument is the new selected state. Only fires when Selectable is set.
func PainterOpt ¶
PainterOpt sets the painter used to render the chip. If not set, DefaultPainter is used.
func Selectable ¶
Selectable makes the chip toggle a selected state on activation (a filter chip). When false (the default), the chip is an action chip that only invokes its OnClick handler.
func Selected ¶
Selected sets the chip's initial selected state. Only meaningful when Selectable is enabled.
func SelectedFn ¶
SelectedFn sets a dynamic selected-state function evaluated on each draw. Using a function (or signal) places the chip in controlled mode: the owner must update the source in response to OnSelectedChanged.
func SelectedReadonlySignal ¶
func SelectedReadonlySignal(sig state.ReadonlySignal[bool]) Option
SelectedReadonlySignal binds the selected state to a read-only signal (controlled mode). Takes highest precedence over all other selected sources.
type PaintState ¶
type PaintState struct {
Label string // chip label text
Bounds geometry.Rect // total widget bounds (excludes outer padding)
Radius float32 // corner radius
FontSize float32 // label font size in logical pixels (0 = painter default)
Selectable bool // chip toggles a selected state
Selected bool // chip is currently selected
Hovered bool // pointer is over the chip
Pressed bool // chip is being pressed
Focused bool // chip has keyboard focus
Disabled bool // chip is disabled
ColorScheme ChipColorScheme // theme-derived colors (zero = use defaults)
}
PaintState provides the current chip state to the painter.
type Painter ¶
type Painter interface {
PaintChip(canvas widget.Canvas, state PaintState)
}
Painter draws the visual representation of a chip. Each design system (Material 3, Fluent, Cupertino) provides its own Painter implementation. If no Painter is set, the chip uses DefaultPainter.
type Widget ¶
type Widget struct {
widget.WidgetBase
// contains filtered or unexported fields
}
Widget implements a compact, interactive chip.
A chip is created with New using functional options:
c := chip.New(
chip.Label("Tag"),
chip.OnClick(handleTag),
)
Fluent styling methods may be chained after construction:
c.Padding(2)
func New ¶
New creates a new chip Widget with the given options.
The returned widget is visible, enabled, and focusable by default.
func (*Widget) IsFocusable ¶
IsFocusable reports whether the chip can currently receive focus. Implements widget.Focusable.
func (*Widget) Mount ¶
Mount creates signal bindings for push-based invalidation. Implements widget.Lifecycle.
func (*Widget) Padding ¶
Padding sets the outer padding around the chip content. Returns the widget for method chaining.
func (*Widget) SetSelected ¶
SetSelected updates the chip's selected state.
If a writable SelectedSignal is bound, the new value is written back to it (two-way binding). With only a static value, the chip's own state is updated. When the selected state is driven by a read-only source (SelectedFn or SelectedReadonlySignal), this is a no-op: the owner controls that source.
func (*Widget) Unmount ¶
func (w *Widget) Unmount()
Unmount is called when the chip is removed from the widget tree. Implements widget.Lifecycle.
Source Files