GoFlow

A Flutter-inspired GUI framework for Go with reactive state management and platform-adaptive design systems.

✨ Single Import Architecture

GoFlow uses a single import path for the best developer experience:

import gf "github.com/base-go/GoFlow"funcmain() {
count:=gf.CreateSignal(0)
app:= gf.MaterialScaffold{
AppBar: gf.MaterialAppBar{Title: "Counter"},
Body: gf.Center{
Child: gf.Text{
Content: fmt.Sprintf("Count: %d", count.Get()),
},
},
}
gf.RunApp(app)
}

Migrating from the old multi-import style? See the Migration Guide

🚀 Quick Start

# Install the CLI
go install github.com/base-go/GoFlow/cmd/goflow@latest
# Create a new project (Flutter-style)
goflow create myapp
# Run itcd myapp/macos
go run main.go

New to GoFlow? → Start with the Getting Started Guide

📚 Documentation

• Migration Guide - Switch to single import architecture
• Getting Started - Complete beginner tutorial
• Architecture - Framework architecture deep dive
• CLI Reference - Complete CLI documentation
• Project Structure - Project organization guide
• Rendering Architecture - How rendering works
• Flutter Comparison - For Flutter developers
• Workflow Guide - Complete technical flow
• All Documentation - Browse all docs

Project Structure

GoFlow follows Flutter's project structure philosophy:

myapp/
├── lib/ # Shared application code (like Flutter's lib/)
│ └── main.go
├── macos/ # macOS platform runner
├── linux/ # Linux platform runner
├── windows/ # Windows platform runner
├── assets/ # Images, fonts, icons
├── test/ # Tests
├── goflow.yaml # Project configuration (like pubspec.yaml)
├── go.mod # Go dependencies
└── README.md

Features

Core Framework

• Signal: Reactive value containers that notify listeners on change
• Computed: Automatically derived values with dependency tracking
• Effect: Side effects that run when dependencies change
• Batch: Group multiple updates to prevent unnecessary recomputation
• Untracked: Read signal values without creating subscriptions
• Collections: Reactive slices and maps with built-in helpers (Filter, Map, etc.)

GUI & Design Systems

• Adaptive Widgets: Automatically switch between Material and Cupertino based on platform
• Material Design: Google's design system (Android, Linux, Windows, Web)
• Cupertino: Apple's design language (iOS, macOS)
• Platform Detection: Automatic platform-specific styling
• Widget System: Declarative UI with reactive updates

Installation

go get github.com/base-go/GoFlow

Signals Quick Start

import gf "github.com/base-go/GoFlow"// Create signalscounter:=gf.CreateSignal(0)
doubled:=gf.CreateComputed(func() int {
returncounter.Get() *2
})
// React to changesdispose:=gf.CreateEffect(func() {
fmt.Printf("Counter: %d, Doubled: %d\n", counter.Get(), doubled.Get())
})
deferdispose()
// Update (triggers effect)counter.Set(5) // Prints: Counter: 5, Doubled: 10

Collections

GoFlow includes reactive collections for common data structures:

SignalSlice

// Create a reactive slicetodos:=signals.NewSlice([]string{"Learn Go", "Build app"})
// Reactive operationstodos.Append("Deploy to production")
todos.Prepend("Plan project")
todos.RemoveAt(1)
// Reactive computed operationsactiveTodos:=todos.Filter(func(todostring) bool {
return!strings.HasPrefix(todo, "Done:")
})
// Get length reactivelycount:=todos.Len()
fmt.Printf("Total todos: %d\n", count.Get())

SignalMap

// Create a reactive mapusers:=signals.NewMap(map[string]int{
"alice": 25,
"bob": 30,
})
// Reactive operationsusers.SetKey("charlie", 35)
users.DeleteKey("bob")
// Reactive querieshasAlice:=users.Has("alice")
aliceAge:=users.GetKey("alice")
userCount:=users.Size()

Advanced Usage

Batch Updates

Prevent unnecessary re-computations by batching multiple updates:

signals.Batch(func() {
firstName.Set("John")
lastName.Set("Doe")
age.Set(30)
})
// Effect runs only once after all updates

Untracked Reads

Read signal values without creating dependencies:

dispose:=signals.NewEffect(func() {
current:=counter.Get() // Trackedprevious:=signals.Untracked(func() int {
returnprevCounter.Get() // Not tracked
})
fmt.Printf("Changed from %d to %d\n", previous, current)
})

Design Systems

GoFlow provides three approaches to building cross-platform UIs:

Adaptive Widgets (Recommended)

Write once, automatically adapts to platform:

import"github.com/base-go/GoFlow/pkg/ui/adaptive"// Button automatically becomes Material or Cupertinobutton:=adaptive.NewButton("Click Me", func() {
fmt.Println("Clicked!")
})
// Card adapts to platform stylecard:=adaptive.NewCard(content)
// AppBar becomes Material AppBar or Cupertino NavigationBarappBar:=adaptive.NewAppBar(title)

Platform-Specific Widgets

Use Material Design or Cupertino explicitly:

// Material Design (Android, Web, Desktop)import"github.com/base-go/GoFlow/pkg/ui/material"btn:=material.NewButton(child, onPressed)
// Cupertino (iOS, macOS)import"github.com/base-go/GoFlow/pkg/ui/cupertino"btn:=cupertino.NewButton(child, onPressed)

See DESIGN_SYSTEMS.md for complete documentation.

Available Widgets

GoFlow includes a comprehensive set of widgets inspired by Flutter:

Layout Widgets

• Column/Row: Vertical/horizontal layout
• Stack: Layered widgets
• Positioned: Position children within Stack
• Align: Align child within parent
• Container: Padding, margin, sizing, colors
• 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/Cupertino): Text input
• Checkbox: Material checkbox
• Radio: Material radio button
• Switch (Material/Cupertino): Toggle switch
• Slider (Material/Cupertino): Value slider

Button Widgets

• Button (Material/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): Basic app structure
• AppBar (Material): Top app bar
• Drawer: Side navigation drawer
• BottomNavigationBar: Bottom navigation
• CupertinoPageScaffold: iOS app structure
• CupertinoNavigationBar: iOS navigation bar
• CupertinoTabScaffold: iOS tabbed interface

Material-Specific

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

Cupertino-Specific

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

📚 See docs/widgets/ for detailed widget documentation with examples

📖 Examples

See the examples directory for complete examples:

Signals Examples

• Playground - Comprehensive framework feature test
• Basic - Simple signal usage
• Counter App - Interactive counter with multiple computed values
• Shopping Cart - Shopping cart with reactive total
• Form Validation - Real-time form validation
• Todo List - Todo list using SignalSlice

Design System Examples

• Adaptive Demo - Platform-adaptive widgets
• Material Demo - Material Design widgets
• Cupertino Demo - iOS/macOS widgets
• Widgets Showcase - Comprehensive widget demonstration

⚡ Performance

GoFlow is designed for performance with:

• Zero allocations for basic signal operations
• Lazy evaluation for computed values
• Efficient dependency tracking using graph algorithms
• Thread-safe operations with minimal locking overhead

Run benchmarks:

go test ./signals -bench=. -benchmem

🎨 Framework Status (v0.2.0)

✅ What Works

• Widget system (Text, Container, Column, Center)
• Reactive signals (Signal, Computed, Effect)
• Signal collections (SignalSlice, SignalMap)
• Layout system (constraints, sizing)
• Three-tree architecture (Widget → Element → RenderObject)
• CLI tool for project creation
• Flutter-inspired project structure
• ✨ macOS Rendering Backend - Core Graphics with native windows
• ✨ Text Rendering - Core Text integration
• ✨ Basic Shapes - Rectangles, circles, lines
• ✨ Event Loop - Native event handling

⏳ In Progress

• Mouse and keyboard event handling
• Image loading and rendering
• More built-in widgets
• Design system implementations (Material, Cupertino)

🔮 Planned

• Windows rendering backend (Direct2D)
• Linux rendering backend (Cairo)
• Hot reload
• Animation system
• Advanced layout widgets (Row, Stack, Grid)
• Input widgets (TextField, Button)
• Platform features (menus, notifications)
• Complete Material Design implementation
• Complete Cupertino implementation

See RENDERING.md, PLATFORM_INTEGRATION.md, and PROGRESS.md for details.

🤝 Contributing

GoFlow is in active development! We welcome contributions:

• 🐛 Report bugs
• 💡 Suggest features
• 📖 Improve documentation
• 🔧 Submit pull requests

See our GitHub repository for more information.

📚 Learn More

• Architecture Guide - Deep dive into the framework
• Getting Started - Step-by-step tutorial
• Workflow Guide - Complete technical flow
• Widget Reference - Complete widget catalog
• Examples - Sample applications
• API Documentation - Go package docs

License

MIT