optimistic

Documentation

Overview

Package optimistic provides instant visual feedback for user interactions.

Deprecated: The v1 Developer Guide recommends optimistic UI via explicit server-side state updates in event handlers. This package is retained for legacy/internal use only.

Optimistic updates allow the thin client to immediately apply visual changes when a user interacts with an element, before the server roundtrip completes. This creates a perceived latency of 0ms for common interactions like button clicks, toggles, and form submissions.

How It Works

When an element has optimistic attributes, the thin client:

1. Captures the user interaction (click, input, etc.)
2. Immediately applies the optimistic changes to the DOM
3. Sends the event to the server
4. When server patches arrive, they replace the optimistic state
5. If the server response differs, the optimistic change is reverted

Available Functions

• OptimisticClass: Toggle a CSS class immediately on click
• OptimisticText: Change text content immediately
• OptimisticAttr: Change an attribute value immediately
• OptimisticParentClass: Toggle a class on the parent element
• OptimisticDisable: Disable the element immediately (prevent double-clicks)
• OptimisticHide: Hide the element immediately

Example Usage

// Like button with instant feedback
func LikeButton(postID string, likes int, userLiked bool) *vdom.VNode {
    return Button(
        Class("like-button"),
        ClassIf(userLiked, "liked"),
        OnClick(func() {
            if userLiked {
                db.Posts.Unlike(postID)
            } else {
                db.Posts.Like(postID)
            }
        }),
        // Instant visual feedback
        OptimisticClass("liked", !userLiked),
        OptimisticText(fmt.Sprintf("%d", likes + boolToInt(!userLiked))),
        Icon("heart"),
        Span(Textf("%d", likes)),
    )
}

Wire Format

Optimistic attributes are rendered as data-optimistic-* attributes:

<button data-hid="h5"
        data-optimistic-class="liked:add"
        data-optimistic-text="43">
    <span>42</span>
</button>

The thin client parses these and applies them immediately on interaction.

Revert Behavior

If the server's response differs from the optimistic prediction (e.g., the like failed due to rate limiting), the client automatically reverts to the server-provided state. This ensures eventual consistency.

Index

• func Attr(name, attrValue string) vdom.Attr
• func AttrRemove(name string) vdom.Attr
• func Class(class string, addNotRemove bool) vdom.Attr
• func ClassToggle(class string) vdom.Attr
• func Disable() vdom.Attr
• func Hide() vdom.Attr
• func Loading(disable bool) vdom.Attr
• func Multiple(attrs ...vdom.Attr) vdom.Attr
• func ParentClass(class string, addNotRemove bool) vdom.Attr
• func ParentClassToggle(class string) vdom.Attr
• func ParseAttrAction(value string) (name, attrValue string, ok bool)
• func ParseMultiple(value string) []struct{ ... }
• func Show() vdom.Attr
• func Swap(html string) vdom.Attr
• func Target(selector string) vdom.Attr
• func Text(newText string) vdom.Attr
• type Action
  • func ParseClassAction(value string) (class string, action Action, ok bool)
• type OptimisticBuilder
  • func Optimistic() *OptimisticBuilder
  • func (b *OptimisticBuilder) Attr(name, value string) *OptimisticBuilder
  • func (b *OptimisticBuilder) AttrRemove(name string) *OptimisticBuilder
  • func (b *OptimisticBuilder) Build() vdom.Attr
  • func (b *OptimisticBuilder) Class(class string, add bool) *OptimisticBuilder
  • func (b *OptimisticBuilder) ClassToggle(class string) *OptimisticBuilder
  • func (b *OptimisticBuilder) Text(text string) *OptimisticBuilder

Functions

func Attr

func Attr(name, attrValue string) vdom.Attr

Attr creates an optimistic attribute change. When the element is clicked, the attribute is immediately set to the new value.

Example:

Input(
    Type("checkbox"),
    Checked(isChecked),
    OnChange(handleChange),
    optimistic.Attr("checked", "true"),
)

func AttrRemove

func AttrRemove(name string) vdom.Attr

AttrRemove creates an optimistic attribute removal. When the element is clicked, the attribute is immediately removed.

Example:

Button(
    Disabled(true),
    OnClick(handleEnable),
    optimistic.AttrRemove("disabled"),
)

func Class

func Class(class string, addNotRemove bool) vdom.Attr

Class creates an optimistic class toggle attribute. When the element is clicked, the class is immediately added or removed based on the addNotRemove parameter.

Example:

Button(
    Class("like-btn"),
    OnClick(handleLike),
    optimistic.Class("liked", true),  // Add "liked" class on click
)

func ClassToggle

func ClassToggle(class string) vdom.Attr

ClassToggle creates an optimistic class toggle attribute. When the element is clicked, the class is toggled (added if absent, removed if present).

Example:

Button(
    Class("menu-toggle"),
    OnClick(handleToggle),
    optimistic.ClassToggle("active"),
)

func Disable

func Disable() vdom.Attr

Disable creates an optimistic disable attribute. When the element is clicked, it's immediately disabled to prevent double-clicks. The server response will restore the correct state.

Example:

Button(
    Text("Submit"),
    OnClick(handleSubmit),
    OptimisticDisable(),
)

func Hide

func Hide() vdom.Attr

Hide creates an optimistic hide attribute. When the element is clicked, it's immediately hidden (display: none).

Example:

Button(
    Text("Dismiss"),
    OnClick(handleDismiss),
    OptimisticHide(),
)

func Loading

func Loading(disable bool) vdom.Attr

Loading creates a loading state optimistic update. Adds a "loading" class and optionally disables the element.

Example:

Button(
    Text("Load More"),
    OnClick(handleLoad),
    OptimisticLoading(true),
)

func Multiple

func Multiple(attrs ...vdom.Attr) vdom.Attr

Multiple combines multiple optimistic updates into a single attribute. This is useful when you need to apply several changes at once.

Example:

Button(
    Text("Submit"),
    OnClick(handleSubmit),
    OptimisticMultiple(
        OptimisticClass("submitting", true),
        OptimisticText("Submitting..."),
        OptimisticDisable(),
    ),
)

func ParentClass

func ParentClass(class string, addNotRemove bool) vdom.Attr

ParentClass creates an optimistic class toggle on the parent element. Useful for dropdown menus, accordions, and similar patterns.

Example:

Button(
    Text("Toggle Menu"),
    OnClick(handleMenu),
    OptimisticParentClass("open", true),
)

func ParentClassToggle

func ParentClassToggle(class string) vdom.Attr

ParentClassToggle creates an optimistic class toggle on the parent element.

Example:

Button(
    Text("Expand"),
    OnClick(handleExpand),
    OptimisticParentClassToggle("expanded"),
)

func ParseAttrAction

func ParseAttrAction(value string) (name, attrValue string, ok bool)

ParseAttrAction parses an attribute action string like "disabled:true". Returns the attribute name, value, and whether parsing succeeded.

func ParseMultiple

func ParseMultiple(value string) []struct{ Key, Value string }

ParseMultiple parses a multiple action string. Returns a slice of key-value pairs.

func Show

func Show() vdom.Attr

Show creates an optimistic show attribute. When the element is clicked, it removes display: none.

Example:

Button(
    Text("Show Details"),
    OnClick(handleShow),
    OptimisticShow(),
)

func Swap

func Swap(html string) vdom.Attr

Swap creates an optimistic content swap. The inner HTML is replaced with the specified content. Use with caution as this can introduce XSS if content is user-provided.

Example:

Div(
    ID("content"),
    OnClick(handleSwap),
    OptimisticSwap("<span class='loading'>Loading...</span>"),
)

func Target

func Target(selector string) vdom.Attr

Target specifies which element should receive the optimistic update. By default, updates apply to the clicked element. This allows targeting a different element by its data-hid or a CSS selector.

Example:

Button(
    Text("Update Header"),
    OnClick(handleUpdate),
    OptimisticTarget("#header"),
    OptimisticClass("updated", true),
)

func Text

func Text(newText string) vdom.Attr

Text creates an optimistic text change attribute. When the element is clicked, the text content is immediately changed to the specified value.

Example:

Button(
    Text("Save"),
    OnClick(handleSave),
    optimistic.Text("Saving..."),
)

Types

type Action

type Action string

Action represents the type of optimistic change.

const (
	ActionAdd    Action = "add"
	ActionRemove Action = "remove"
	ActionSet    Action = "set"
	ActionToggle Action = "toggle"
)

func ParseClassAction

func ParseClassAction(value string) (class string, action Action, ok bool)

ParseClassAction parses a class action string like "liked:add" or "active:toggle". Returns the class name, action, and whether parsing succeeded.

type OptimisticBuilder

type OptimisticBuilder struct {
	// contains filtered or unexported fields
}

OptimisticBuilder combines multiple optimistic options into one config. Use the Optimistic() function to create a builder, then chain methods.

Example:

Button(
    Text("Submit"),
    OnClick(handleSubmit),
    Optimistic().
        Class("submitting", true).
        Text("Submitting...").
        Build(),
)

func Optimistic

func Optimistic() *OptimisticBuilder

Optimistic creates a new builder for chaining optimistic updates.

func (*OptimisticBuilder) Attr

func (b *OptimisticBuilder) Attr(name, value string) *OptimisticBuilder

Attr sets an attribute modification.

func (*OptimisticBuilder) AttrRemove

func (b *OptimisticBuilder) AttrRemove(name string) *OptimisticBuilder

AttrRemove sets an attribute for removal.

func (*OptimisticBuilder) Build

func (b *OptimisticBuilder) Build() vdom.Attr

Build returns a vdom.Attr with _optimistic prop containing OptimisticConfig.

func (*OptimisticBuilder) Class

func (b *OptimisticBuilder) Class(class string, add bool) *OptimisticBuilder

Class adds a class modification to the builder.

func (*OptimisticBuilder) ClassToggle

func (b *OptimisticBuilder) ClassToggle(class string) *OptimisticBuilder

ClassToggle adds a class toggle to the builder.

func (*OptimisticBuilder) Text

func (b *OptimisticBuilder) Text(text string) *OptimisticBuilder

Text sets the optimistic text replacement.