widgets
Package widgets provides UI components for building widget trees.
This package contains the concrete widget implementations that developers use to build user interfaces, including layout widgets (Row, Column, Stack), display widgets (Text, Icon, Image), input widgets (Button, TextField, Checkbox), and container widgets (Container, Padding, SizedBox).
Widget Construction
Drift widgets use a two-tier construction pattern:
Tier 1: Struct Literal \(canonical, full control\)
btn := Button{
Label: "Submit",
OnTap: handleSubmit,
Color: colors.Primary,
Disabled: !isValid,
Haptic: true,
}
This is the PRIMARY way to create widgets. All fields are accessible. For themed styling, use theme.XxxOf constructors from pkg/theme instead.
Tier 2: Layout Helpers \(ergonomics for layout widgets\)
Convenience helpers for common layout patterns:
StackOf, VSpace, HSpace, Centered.
WithX Chaining \(for themed widgets\)
WithX methods on widgets allow overriding themed defaults:
btn := theme.ButtonOf(ctx, "Submit", handleSubmit).
WithBorderRadius(0). // Sharp corners
WithPadding(layout.EdgeInsetsAll(20))
WithX methods return COPIES; they never mutate the receiver.
API Rules
- Canonical = struct literal. Always works, always documented.
- Layout helpers (StackOf, VSpace, HSpace, Centered) exist for ergonomics.
- For themed widgets, use theme.XxxOf constructors from pkg/theme.
- WithX returns copies. Doc comment must state "returns a copy".
Layout Widgets
Use Row and Column struct literals for horizontal and vertical layouts:
widgets.Row{Children: []core.Widget{...}}
widgets.Column{Children: []core.Widget{...}}
Input Widgets
Button, TextField, Checkbox, Radio, and Switch handle user input. Use struct literals for explicit control or theme.XxxOf for themed widgets:
// Struct literal (explicit)
widgets.Button{Label: "Submit", OnTap: onTap, Color: colors.Primary, Haptic: true}
// Themed constructor (from pkg/theme)
theme.ButtonOf(ctx, "Submit", onTap)
Scrolling
ScrollView provides scrollable content with customizable physics:
widgets.ScrollView{Child: content, Physics: widgets.BouncingScrollPhysics{}}
Style Guide for Widget Authors
When adding WithX methods:
- Use value receiver, not pointer
- Return the modified copy, never mutate
- Doc comment: "returns a copy of X with..."
Constants
const (
// ActivityIndicatorSizeMedium is a medium spinner.
ActivityIndicatorSizeMedium = platform.ActivityIndicatorSizeMedium
// ActivityIndicatorSizeSmall is a small spinner.
ActivityIndicatorSizeSmall = platform.ActivityIndicatorSizeSmall
// ActivityIndicatorSizeLarge is a large spinner.
ActivityIndicatorSizeLarge = platform.ActivityIndicatorSizeLarge
)
Variables
var (
SnapThird = SnapPoint{FractionalHeight: 0.33, Name: "third"}
SnapHalf = SnapPoint{FractionalHeight: 0.5, Name: "half"}
SnapFull = SnapPoint{FractionalHeight: 1.0, Name: "full"}
)
DefaultSnapPoints is used when no snap points are provided.
var DefaultSnapPoints = []SnapPoint{SnapFull}
func Clamp
func Clamp(value, min, max float64) float64
Clamp constrains a value between min and max bounds.
func DeviceScaleOf
func DeviceScaleOf(ctx core.BuildContext) float64
DeviceScaleOf returns the current device scale, defaulting to 1 if not found.
func HandleDropdownPointerDown
func HandleDropdownPointerDown(entries []layout.RenderObject)
HandleDropdownPointerDown dismisses open dropdowns on outside taps.
func HasActiveBallistics
func HasActiveBallistics() bool
HasActiveBallistics returns true if any scroll simulations are running.
func RegisterRestartAppFn
func RegisterRestartAppFn(fn func())
RegisterRestartAppFn registers the function to restart the app. This is called by the engine package during initialization.
func SafeAreaBottomOf
func SafeAreaBottomOf(ctx core.BuildContext) float64
SafeAreaBottomOf returns only the bottom safe area inset. Widgets calling this will only rebuild when the bottom inset changes.
func SafeAreaLeftOf
func SafeAreaLeftOf(ctx core.BuildContext) float64
SafeAreaLeftOf returns only the left safe area inset. Widgets calling this will only rebuild when the left inset changes.
func SafeAreaOf
func SafeAreaOf(ctx core.BuildContext) layout.EdgeInsets
SafeAreaOf returns the current safe area insets from context. Widgets calling this will rebuild when any inset changes.
func SafeAreaPadding
func SafeAreaPadding(ctx core.BuildContext) layout.EdgeInsets
SafeAreaPadding returns the safe area insets as EdgeInsets for use with ScrollView.Padding or other widgets. The returned EdgeInsets can be modified using chainable methods:
ScrollView{
Padding: widgets.SafeAreaPadding(ctx), // just safe area
Child: ...,
}
ScrollView{
Padding: widgets.SafeAreaPadding(ctx).Add(24), // safe area + 24px all sides
Child: ...,
}
ScrollView{
Padding: widgets.SafeAreaPadding(ctx).OnlyTop().Add(24), // only top safe area + 24px
Child: ...,
}
func SafeAreaRightOf
func SafeAreaRightOf(ctx core.BuildContext) float64
SafeAreaRightOf returns only the right safe area inset. Widgets calling this will only rebuild when the right inset changes.
func SafeAreaTopOf
func SafeAreaTopOf(ctx core.BuildContext) float64
SafeAreaTopOf returns only the top safe area inset. Widgets calling this will only rebuild when the top inset changes.
func StepBallistics
func StepBallistics()
StepBallistics advances any active scroll simulations.
func ValidateInitialSnap
func ValidateInitialSnap(index int, points []SnapPoint) int
ValidateInitialSnap ensures the initial snap index is valid.
type ActivityIndicator
ActivityIndicator displays a native platform spinner. Uses UIActivityIndicatorView on iOS and ProgressBar on Android.
type ActivityIndicator struct {
core.StatefulBase
// Animating controls whether the indicator is spinning.
// Defaults to true.
Animating bool
// Size is the indicator size (Small, Medium, Large).
// Defaults to Medium.
Size ActivityIndicatorSize
// Color is the spinner color (optional, uses system default if not set).
Color graphics.Color
}
func (ActivityIndicator) CreateState
func (a ActivityIndicator) CreateState() core.State
type ActivityIndicatorSize
ActivityIndicatorSize represents the size of the activity indicator.
type ActivityIndicatorSize = platform.ActivityIndicatorSize
type Align
Align positions its child within itself according to the given alignment.
Align expands to fill available space, then positions the child within that space according to the Alignment field. The child is given loose constraints, allowing it to size itself.
Example:
Align{
Alignment: layout.AlignmentBottomRight,
Child: Text{Content: "Bottom right"},
}
See also:
- Center for centering (equivalent to Align with AlignmentCenter)
- Container for combined alignment, padding, and decoration
type Align struct {
core.RenderObjectBase
Child core.Widget
Alignment layout.Alignment
}
func (Align) ChildWidget
func (a Align) ChildWidget() core.Widget
func (Align) CreateRenderObject
func (a Align) CreateRenderObject(ctx core.BuildContext) layout.RenderObject
func (Align) UpdateRenderObject
func (a Align) UpdateRenderObject(ctx core.BuildContext, renderObject layout.RenderObject)
type AnimatedContainer
AnimatedContainer is a Container that animates changes to its properties.
When properties like Color, Width, Height, Padding, or Alignment change, the widget automatically animates from the old value to the new value over the specified Duration using the specified Curve.
Note: Gradient is not animated; changes to Gradient will apply immediately.
Example:
widgets.AnimatedContainer{
Duration: 300 * time.Millisecond,
Curve: animation.EaseInOut,
Color: s.isActive ? colors.Primary : colors.Surface,
Width: 100,
Height: 100,
Child: child,
}
type AnimatedContainer struct {
core.StatefulBase
// Duration is the length of the animation.
Duration time.Duration
// Curve transforms the animation progress. If nil, uses linear interpolation.
Curve func(float64) float64
// OnEnd is called when the animation completes.
OnEnd func()
// Container properties that will be animated when they change.
Padding layout.EdgeInsets
Width float64
Height float64
Color graphics.Color
Gradient *graphics.Gradient
Alignment layout.Alignment
Child core.Widget
}
Example:
This example shows implicit animation with AnimatedContainer.
package main
import (
"time"
"github.com/go-drift/drift/pkg/animation"
"github.com/go-drift/drift/pkg/graphics"
"github.com/go-drift/drift/pkg/widgets"
)
func main() {
var isExpanded bool
// Properties animate automatically when they change
container := widgets.AnimatedContainer{
Duration: 300 * time.Millisecond,
Curve: animation.EaseInOut,
Width: func() float64 {
if isExpanded {
return 200
} else {
return 100
}
}(),
Height: func() float64 {
if isExpanded {
return 200
} else {
return 100
}
}(),
Color: func() graphics.Color {
if isExpanded {
return graphics.RGB(100, 149, 237)
} else {
return graphics.RGB(200, 200, 200)
}
}(),
Child: widgets.Center{Child: widgets.Text{Content: "Tap to toggle"}},
}
_ = container
}
func (AnimatedContainer) CreateState
func (a AnimatedContainer) CreateState() core.State
type AnimatedOpacity
AnimatedOpacity animates changes to opacity over a duration.
When the Opacity property changes, the widget automatically animates from the old value to the new value over the specified Duration.
Example:
widgets.AnimatedOpacity{
Duration: 200 * time.Millisecond,
Curve: animation.EaseOut,
Opacity: s.isVisible ? 1.0 : 0.0,
Child: child,
}
type AnimatedOpacity struct {
core.StatefulBase
// Duration is the length of the animation.
Duration time.Duration
// Curve transforms the animation progress. If nil, uses linear interpolation.
Curve func(float64) float64
// OnEnd is called when the animation completes.
OnEnd func()
// Opacity is the target opacity (0.0 to 1.0).
Opacity float64
// Child is the widget to which opacity is applied.
Child core.Widget
}
Example:
This example shows fade animation with AnimatedOpacity.
package main
import (
"time"
"github.com/go-drift/drift/pkg/animation"
"github.com/go-drift/drift/pkg/widgets"
)
func main() {
var isVisible bool
opacity := widgets.AnimatedOpacity{
Duration: 200 * time.Millisecond,
Curve: animation.EaseOut,
Opacity: func() float64 {
if isVisible {
return 1.0
} else {
return 0.0
}
}(),
Child: widgets.Text{Content: "Fading content"},
}
_ = opacity
}
func (AnimatedOpacity) CreateState
func (a AnimatedOpacity) CreateState() core.State
type Axis
Axis represents the layout direction. AxisVertical is the zero value, making it the default for ScrollDirection fields.
type Axis int
const (
AxisVertical Axis = iota
AxisHorizontal
)
func (Axis) String
func (a Axis) String() string
String returns a human-readable representation of the axis.
type BackdropFilter
BackdropFilter applies a blur effect to content behind this widget. The blur is applied within the widget's bounds and affects any content drawn before this widget in the compositing order.
type BackdropFilter struct {
core.RenderObjectBase
Child core.Widget
SigmaX float64
SigmaY float64
}
func NewBackdropFilter
func NewBackdropFilter(sigma float64, child core.Widget) BackdropFilter
NewBackdropFilter creates a BackdropFilter with uniform blur in both directions.
func (BackdropFilter) ChildWidget
func (b BackdropFilter) ChildWidget() core.Widget
func (BackdropFilter) CreateRenderObject
func (b BackdropFilter) CreateRenderObject(ctx core.BuildContext) layout.RenderObject
func (BackdropFilter) UpdateRenderObject
func (b BackdropFilter) UpdateRenderObject(ctx core.BuildContext, renderObject layout.RenderObject)