Combobox

Client-mode comboboxes toggle entirely in the browser (no HTTP on open/select); server-mode keeps an HTMX lazy/search path for options that can't be pre-rendered.

Industry (client mode)

Usage Example

// Client mode: options are pre-rendered, toggling happens in the browser.
var IndustryCfg = combobox.Config{
    ID: "industry", Name: "industry", Label: "Industry",
    Mode:   combobox.ModeSingle,
    Source: combobox.Source{Static: industryOptions},
}
@combobox.Combobox(IndustryCfg, combobox.State{Options: IndustryCfg.Source.Static})

Client Multi-Select

Mode: combobox.ModeMultiple with EnableClearAll — still fully client-side.

Client Multi-Select

var SkillsCfg = combobox.Config{
    ID: "skills", Name: "skills", Mode: combobox.ModeMultiple, EnableClearAll: true,
    Source: combobox.Source{Static: skillOptions},
}
@combobox.Combobox(SkillsCfg, combobox.State{Options: SkillsCfg.Source.Static})

Selected and Disabled Options

Set Config.Selected for first-paint values. Disabled options stay visible but cannot be selected.

Region

Selected and Disabled Options

var RegionsCfg = combobox.Config{
    ID: "region", Name: "region", Label: "Region",
    Selected: []string{"us-east-1"},
    Source: combobox.Source{Static: []combobox.Option{
        {Value: "us-east-1", Label: "US East"},
        {Value: "legacy", Label: "Legacy region", Disabled: true},
    }},
}
@combobox.Combobox(RegionsCfg, RegionsCfg.InitialState())

Server Mode (lazy search)

Set the Toggle/Options/Clear endpoints and a LazyEndpoint Source; the component fetches and searches options over HTMX.

Users (server mode, lazy)

Server Mode (lazy search)

var UsersCfg = combobox.Config{
    ID: "users", Name: "users", Mode: combobox.ModeMultiple,
    EnableSearch: true, EnableClearAll: true,
    ToggleEndpoint:  "/api/.../toggle",
    OptionsEndpoint: "/api/.../options",
    ClearEndpoint:   "/api/.../clear",
    Source: combobox.Source{LazyEndpoint: "/api/.../options"},
}
@combobox.Combobox(UsersCfg, combobox.State{})

Cascading Server Filters

DependsOn adds other fields to combobox HTMX requests. Add an hx-get on the parent field when changing it should immediately refresh the dependent options.

Provider

Cluster

Cascading Server Filters

selectedProvider := "aws"
var ClusterCfg = combobox.Config{
    ID: "cluster", Name: "cluster", Mode: combobox.ModeSingle,
    EnableSearch: true,
    DependsOn: []string{"provider"},
    ToggleEndpoint:  "/api/.../clusters/toggle",
    OptionsEndpoint: "/api/.../clusters/options",
    ClearEndpoint:   "/api/.../clusters/clear",
    Source: combobox.Source{LazyEndpoint: "/api/.../clusters/options"},
}

// OptionsProvider receives search and deps["provider"] on the server.
clustersProvider := func(ctx context.Context, search string, deps map[string]string) ([]combobox.Option, error) {
    return clustersForProvider(deps["provider"], search)
}

<select
    name="provider"
    hx-get={ ClusterCfg.OptionsEndpoint }
    hx-trigger="change"
    hx-target="#cluster-options"
    hx-swap="outerHTML"
    hx-include="#cluster [data-combobox-search], #cluster input[type=hidden]">
    <option value={ selectedProvider }>AWS</option>
</select>
@combobox.Combobox(ClusterCfg, combobox.State{})

API Reference

Prop	Type	Default	Description
`ID`	`string`	`""`	Unique id (seeds #<id>-trigger, options, hidden inputs).
`Name`	`string`	`""`	Form field name (multi-select submits repeated hidden inputs).
`Label`	`string`	`""`	Label above the combobox.
`Placeholder`	`string`	`""`	Trigger placeholder.
`Mode`	`Mode`	`ModeSingle`	combobox.ModeSingle or combobox.ModeMultiple.
`Source.Static`	`[]Option`	`nil`	Client-mode options rendered into the first page. Use InitialState() to pass them into State.
`Source.LazyEndpoint`	`string`	`""`	Server-mode endpoint used for first load/search. Cannot be combined with Source.Static.
`Option`	`struct`	`-`	Option row fields: Value, Label, Disabled. Meta, Img, Initials, Badge, and BadgeColor are data-model fields not rendered by the current list template.
`Selected`	`[]string`	`nil`	Initial selected values for first-paint/static renders.
`State.Options`	`[]Option`	`nil`	Options available for this render. Client mode usually uses cfg.InitialState().
`State.Selected`	`[]string`	`nil`	Selected values for this render; server handlers return updated Body/OptionsList state.
`State.Search`	`string`	`""`	Current server-side search term used when rendering filtered results.
`OptionsProvider`	`func`	`nil`	Server helper shape: func(ctx, search, deps) ([]combobox.Option, error).
`EnableSearch`	`bool`	`false`	Show a search box (server mode queries the endpoint).
`EnableClearAll`	`bool`	`false`	Show a clear-all action.
`Required`	`bool`	`false`	Mark the field required.
`DependsOn`	`[]string`	`nil`	Other field names included in server HTMX requests via hx-include.
`ToggleEndpoint`	`string`	`""`	Server URL for toggling a selection (server mode).
`OptionsEndpoint`	`string`	`""`	Server URL for fetching/searching options.
`ClearEndpoint`	`string`	`""`	Server URL for clearing the selection.
`Disabled`	`bool`	`false`	Disable interaction.
`RootClass`	`string`	`""`	Extra classes on the container.

Checkbox File Input