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 LayoutMetrics
- 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) ChipFontSize ¶ added in v0.1.37
func (DefaultPainter) ChipFontSize() float32
ChipFontSize returns the default font size.
func (DefaultPainter) ChipMinWidth ¶ added in v0.1.37
func (DefaultPainter) ChipMinWidth() float32
ChipMinWidth returns the default minimum chip width.
func (DefaultPainter) ChipPadding ¶ added in v0.1.37
func (DefaultPainter) ChipPadding() float32
ChipPadding returns the default horizontal padding.
func (DefaultPainter) ChipRadius ¶ added in v0.1.37
func (DefaultPainter) ChipRadius() float32
ChipRadius returns the default corner radius.
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 LayoutMetrics ¶ added in v0.1.37
type LayoutMetrics interface {
// ChipFontSize returns the font size for the chip label.
ChipFontSize() float32
// ChipMinWidth returns the minimum chip width in logical pixels.
ChipMinWidth() float32
// ChipPadding returns the horizontal padding inside the chip.
ChipPadding() float32
// ChipRadius returns the corner radius for the chip.
ChipRadius() float32
}
LayoutMetrics allows theme painters to provide spatial metrics used by the widget's Layout method to compute chip dimensions.
Painters that implement this interface provide custom metrics. Painters that do not implement it get default values from DefaultPainter.
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