widgets

GoFlow Widgets Documentation

Complete reference for all GoFlow widgets with examples and best practices.

Widget Categories

Layout Widgets

• Column & Row - Vertical and horizontal layouts
• Stack - Layered widgets
• Positioned - Position children within Stack
• Align - Align child within parent
• Container - Decoration, padding, margin, sizing
• Center - Center child widget
• Padding - Add padding around child
• SizedBox - Fixed size container
• Expanded & Flexible - Flex children in Row/Column
• Spacer - Empty space in flex layouts

Form Widgets

• TextField - Material and Cupertino text input
• Checkbox - Material checkbox
• Radio - Material radio button
• Switch - Material and Cupertino toggle switch
• Slider - Material and Cupertino value slider

Button Widgets

• Button - Material and Cupertino primary buttons
• TextButton - Text-only button (Material)
• OutlinedButton - Outlined button (Material)
• IconButton - Button with icon
• FloatingActionButton - Material FAB

Display Widgets

• Text - Display text
• Icon - Display icons
• Image - Display images

Scrolling Widgets

• ListView - Scrollable list
• ListView.builder - Lazy-loaded list
• GridView - Scrollable grid
• SingleChildScrollView - Scrollable single child

Interaction Widgets

• GestureDetector - Detect gestures
• InkWell - Material ink splash effect
• Draggable - Make widget draggable
• DragTarget - Accept draggable widgets

App Structure

• Scaffold - Material app structure
• CupertinoPageScaffold - iOS app structure
• CupertinoTabScaffold - iOS tabbed interface
• AppBar - Material top app bar
• CupertinoNavigationBar - iOS navigation bar
• Drawer - Side navigation drawer
• BottomNavigationBar - Bottom navigation

Material-Specific Widgets

• Card - Material card
• ListTile - List item with leading/trailing
• Dialog - Material dialog
• AlertDialog - Alert dialog with actions
• DrawerHeader - Drawer header

Cupertino-Specific Widgets

• CupertinoTextField - iOS text field
• CupertinoSwitch - iOS switch
• CupertinoSlider - iOS slider

Quick Reference

Creating Widgets

import (
    "github.com/base-go/GoFlow/widgets"
    "github.com/base-go/GoFlow/material"
    "github.com/base-go/GoFlow/cupertino"
    "github.com/base-go/GoFlow/adaptive"
)

// Layout
column := &widgets.Column{Children: []goflow.Widget{...}}
row := &widgets.Row{Children: []goflow.Widget{...}}
container := &widgets.Container{Child: child, Padding: padding}

// Material
button := material.NewButton(child, onPressed)
card := material.NewCard(child)

// Cupertino
button := cupertino.NewButton(child, onPressed)
card := cupertino.NewCard(child)

// Adaptive (recommended for cross-platform)
button := adaptive.NewButton("Text", onPressed)
card := adaptive.NewCard(child)

Common Patterns

Center a widget:

&widgets.Center{
    Child: myWidget,
}

Add padding:

&widgets.Container{
    Padding: goflow.NewEdgeInsets(16, 16, 16, 16),
    Child: myWidget,
}

Create a list:

&widgets.ListView{
    Children: []goflow.Widget{
        item1,
        item2,
        item3,
    },
}

Responsive layout:

&widgets.Row{
    Children: []goflow.Widget{
        &widgets.Expanded{Child: widget1},
        &widgets.Expanded{Child: widget2},
    },
}

Widget Lifecycle

All widgets in GoFlow follow this lifecycle:

1. Construction - Widget is created with New...() or struct literal
2. Build - Build(context) is called to create the widget tree
3. Mount - Element is created and mounted to parent
4. Update - When properties change, widget is rebuilt
5. Unmount - Widget is removed from tree

Best Practices

1. Use Adaptive Widgets for Cross-Platform Apps

// ✅ Good - works on all platforms
adaptive.NewButton("Click Me", onPressed)

// ❌ Less ideal - platform-specific
material.NewButton(child, onPressed)

2. Prefer Stateless Widgets with Signals

// ✅ Good - reactive with signals
counter := signals.New(0)
&widgets.Text{
    Data: fmt.Sprintf("Count: %d", counter.Get()),
}

// ❌ Less ideal - requires manual updates

3. Use const for Repeated Values

const (
    padding = 16.0
    spacing = 8.0
)

&widgets.Container{
    Padding: goflow.NewEdgeInsets(padding, padding, padding, padding),
    Child: child,
}

4. Extract Complex Widgets into Functions

func buildHeader(title string) goflow.Widget {
    return &widgets.Container{
        Padding: goflow.NewEdgeInsets(16, 8, 16, 8),
        Child: &widgets.Text{Data: title},
    }
}

5. Use ListView.builder for Large Lists

// ✅ Good - efficient for large lists
&widgets.ListViewBuilder{
    ItemCount: 1000,
    ItemBuilder: func(ctx goflow.BuildContext, i int) goflow.Widget {
        return &widgets.Text{Data: fmt.Sprintf("Item %d", i)}
    },
}

// ❌ Avoid - creates all items upfront
&widgets.ListView{
    Children: make1000Items(),
}

Widget Composition

GoFlow widgets are highly composable. Build complex UIs by combining simple widgets:

func buildProfileCard(name, email string) goflow.Widget {
    return material.NewCard(&widgets.Column{
        Children: []goflow.Widget{
            &widgets.Row{
                Children: []goflow.Widget{
                    widgets.NewIcon(widgets.IconPerson),
                    &widgets.Expanded{
                        Child: &widgets.Text{Data: name},
                    },
                },
            },
            &widgets.Text{Data: email},
        },
    })
}

Platform-Specific Behavior

Some widgets behave differently on different platforms:

Widget	Android/Linux/Web	iOS/macOS
Button	Material Design	Cupertino
TextField	Underline	Rounded rectangle
Switch	Material toggle	iOS toggle
AppBar	Material AppBar	NavigationBar

Use adaptive package to handle these differences automatically.

Next Steps

• Explore widget categories in detail
• Check out examples for real-world usage
• Read DESIGN_SYSTEMS.md for design system guide