button

README

Button Component

Versatile button component with multiple variants, sizes, and states.

Features

• 🎨 6 Variants: Default, Secondary, Destructive, Outline, Ghost, Link
• 📏 4 Sizes: SM, MD (default), LG, Icon
• ⚡ States: Disabled, Loading
• 🔧 Flexible: Custom classes, attributes, and children
• ♿ Accessible: Proper ARIA attributes and keyboard navigation

Basic Usage

import (
    "github.com/xraph/forgeui/components/button"
    g "maragu.dev/gomponents"
)

// Simple button
btn := button.Button(g.Text("Click me"))

// With options
btn := button.Button(
    g.Text("Save"),
    button.WithVariant(forgeui.VariantDefault),
    button.WithSize(forgeui.SizeLG),
)

Variants

Default (Primary)

button.Button(g.Text("Primary Action"))
// or
button.Primary(g.Text("Primary Action"))

Secondary

button.Secondary(g.Text("Secondary Action"))

Destructive

button.Destructive(g.Text("Delete"))

Outline

button.Outline(g.Text("Cancel"))

Ghost

button.Ghost(g.Text("Skip"))

Link

button.Link(g.Text("Learn More"))

Sizes

// Small
button.Button(g.Text("Small"), button.WithSize(forgeui.SizeSM))

// Medium (default)
button.Button(g.Text("Medium"))

// Large
button.Button(g.Text("Large"), button.WithSize(forgeui.SizeLG))

// Icon (square)
button.IconButton(icons.X())

States

Disabled

button.Button(
    g.Text("Disabled"),
    button.Disabled(),
)

Loading

button.Button(
    g.Text("Saving..."),
    button.Loading(),
)

Button Types

// Submit button (for forms)
button.Button(
    g.Text("Submit"),
    button.WithType("submit"),
)

// Reset button
button.Button(
    g.Text("Reset"),
    button.WithType("reset"),
)

With Icons

import "github.com/xraph/forgeui/icons"

// Icon + Text
button.Primary(
    g.Group([]g.Node{
        icons.Plus(icons.WithSize(16)),
        g.Text("Add Item"),
    }),
)

// Icon only
button.IconButton(
    icons.Settings(),
    button.WithVariant(forgeui.VariantGhost),
)

Button Group

Group related buttons together:

btnGroup := button.Group(
    []button.GroupOption{
        button.WithGap("2"),
    },
    button.Primary(g.Text("Save")),
    button.Secondary(g.Text("Cancel")),
)

Custom Styling

button.Button(
    g.Text("Custom"),
    button.WithClass("shadow-lg hover:shadow-xl"),
)

Custom Attributes

button.Button(
    g.Text("Track Me"),
    button.WithAttrs(
        g.Attr("data-analytics", "signup-button"),
        g.Attr("id", "signup-btn"),
    ),
)

Complete Example

func SaveForm() g.Node {
    return primitives.Flex(
        primitives.FlexGap("4"),
        primitives.FlexChildren(
            button.Primary(
                g.Group([]g.Node{
                    icons.Check(icons.WithSize(16)),
                    g.Text("Save Changes"),
                }),
                button.WithType("submit"),
            ),
            button.Outline(
                g.Text("Cancel"),
                button.WithType("button"),
            ),
            button.Destructive(
                g.Group([]g.Node{
                    icons.Trash(icons.WithSize(16)),
                    g.Text("Delete"),
                }),
            ),
        ),
    )
}

Best Practices

1. Use semantic variants: Primary for main actions, Destructive for dangerous actions
2. Add loading states: Show feedback during async operations
3. Icon + Text: Combine icons with text for clarity
4. Proper types: Use type="submit" for form submissions
5. Disabled vs Loading: Use Loading() for async operations, Disabled() for unavailable actions
6. Accessibility: Add aria-label for icon-only buttons

Styling

The button uses CVA (Class Variance Authority) for consistent styling:

• Base classes for layout and transitions
• Variant classes for colors and styles
• Size classes for dimensions
• Focus states for keyboard navigation
• Dark mode support built-in

Documentation

Overview

Package button provides button components with multiple variants, sizes, and states following shadcn/ui design patterns.

Index

• func Button(children g.Node, opts ...Option) g.Node
• func Destructive(children g.Node, opts ...Option) g.Node
• func Ghost(children g.Node, opts ...Option) g.Node
• func Group(opts []GroupOption, children ...g.Node) g.Node
• func IconButton(children g.Node, opts ...Option) g.Node
• func Link(children g.Node, opts ...Option) g.Node
• func Outline(children g.Node, opts ...Option) g.Node
• func Primary(children g.Node, opts ...Option) g.Node
• func Secondary(children g.Node, opts ...Option) g.Node
• type GroupOption
  • func WithGap(gap string) GroupOption
  • func WithGroupClass(class string) GroupOption
• type GroupProps
• type Option
  • func Disabled() Option
  • func Loading() Option
  • func WithAttrs(attrs ...g.Node) Option
  • func WithClass(class string) Option
  • func WithSize(s forgeui.Size) Option
  • func WithType(t string) Option
  • func WithVariant(v forgeui.Variant) Option
• type Props

Functions

func Button

func Button(children g.Node, opts ...Option) g.Node

Button creates a button component

Example:

btn := button.Button(
    g.Text("Click me"),
    button.WithVariant(forgeui.VariantPrimary),
    button.WithSize(forgeui.SizeLG),
)

func Destructive

func Destructive(children g.Node, opts ...Option) g.Node

Destructive creates a destructive/danger button

func Ghost

func Ghost(children g.Node, opts ...Option) g.Node

Ghost creates a ghost button

func Group

func Group(opts []GroupOption, children ...g.Node) g.Node

Group creates a button group container Useful for grouping related buttons together

Example:

btnGroup := button.Group(
    button.WithGap("2"),
    button.Primary(g.Text("Save")),
    button.Secondary(g.Text("Cancel")),
)

func IconButton

func IconButton(children g.Node, opts ...Option) g.Node

IconButton creates an icon-only button

func Link

func Link(children g.Node, opts ...Option) g.Node

Link creates a link-styled button

func Outline

func Outline(children g.Node, opts ...Option) g.Node

Outline creates an outline button

func Primary

func Primary(children g.Node, opts ...Option) g.Node

Primary creates a primary button (alias for default variant)

func Secondary

func Secondary(children g.Node, opts ...Option) g.Node

Secondary creates a secondary button

Types

type GroupOption

type GroupOption func(*GroupProps)

GroupOption is a functional option for configuring button groups

func WithGap

func WithGap(gap string) GroupOption

WithGap sets the gap between buttons

func WithGroupClass

func WithGroupClass(class string) GroupOption

WithGroupClass adds custom classes to the button group

type GroupProps

type GroupProps struct {
	Gap   string
	Class string
}

GroupProps defines button group configuration

type Option

type Option func(*Props)

Option is a functional option for configuring the button

func Disabled

func Disabled() Option

Disabled sets the disabled state

func Loading

func Loading() Option

Loading sets the loading state (also disables the button)

func WithAttrs

func WithAttrs(attrs ...g.Node) Option

WithAttrs adds custom attributes

func WithClass

func WithClass(class string) Option

WithClass adds custom classes

func WithSize

func WithSize(s forgeui.Size) Option

WithSize sets the button size

func WithType

func WithType(t string) Option

WithType sets the button type attribute

func WithVariant

func WithVariant(v forgeui.Variant) Option

WithVariant sets the visual variant

type Props

type Props struct {
	Variant  forgeui.Variant
	Size     forgeui.Size
	Type     string // button, submit, reset
	Disabled bool
	Loading  bool
	Class    string
	Attrs    []g.Node
}

Props defines button component configuration