form

package
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 2, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package form is a library of form input widgets.

Index

Constants

This section is empty.

Variables

View Source 
var Any = factory.Any

Function aliases

View Source 
var Bytes = factory.Bytes
View Source 
var HTML = factory.HTML
View Source 
var HTMLUnsafe = factory.HTMLUnsafe
View Source 
var Many = factory.Many
View Source 
var Tag = factory.Tag
View Source 
var Text = factory.Text

Functions

This section is empty.

Types

type AlertWidget 

type AlertWidget struct {
	*widget.WidgetBase[*AlertWidget]
	// contains filtered or unexported fields
}

AlertWidget renders an alert modal.

func (*AlertWidget) Add 

func (wgt *AlertWidget) Add(children ...any) *AlertWidget

Add appends widgets to the alert's body. Buttons get special handling: clicking any button clears the alert's state variable (closing the modal), and a named button additionally writes its own state variable to the closed alert's prior value — so the handler can dispatch on which button was pressed and still see the row ID. Example: alert "delete" set to "42"; clicking button "confirm" results in `?delete=&confirm=42`.

func (*AlertWidget) Children 

func (wgt *AlertWidget) Children() []Widget

Children are the widgets nested under this widget.

func (*AlertWidget) Draw 

func (wgt *AlertWidget) Draw(w io.Writer, r *http.Request) (err error)

Draw renders the widget's HTML.

func (*AlertWidget) Drawn 

func (wgt *AlertWidget) Drawn(r *http.Request) bool

Drawn indicates whether this widget needs to be drawn.

func (*AlertWidget) WithWidth 

func (wgt *AlertWidget) WithWidth(css string) *AlertWidget

WithWidth sets the width of the alert window. Pass any CSS length, e.g. "450px", "90%" or "calc(100vw - 2em)". Empty clears it. The default is 450px.

type ButtonWidget 

type ButtonWidget struct {
	*widget.InputWidgetBase[*ButtonWidget]
	// contains filtered or unexported fields
}

ButtonWidget renders a button.

func (*ButtonWidget) Add 

func (wgt *ButtonWidget) Add(children ...any) *ButtonWidget

Add adds nested widgets.

func (*ButtonWidget) Changed 

func (wgt *ButtonWidget) Changed(r *http.Request) bool

Changed indicates if the value of the field changed.

func (*ButtonWidget) Children 

func (wgt *ButtonWidget) Children() []Widget

Children are the widgets nested under this widget.

func (*ButtonWidget) Draw 

func (wgt *ButtonWidget) Draw(w io.Writer, r *http.Request) (err error)

Draw renders the widget's HTML.

func (*ButtonWidget) Pressed 

func (wgt *ButtonWidget) Pressed(r *http.Request) bool

Pressed reports whether this button was just clicked. Use this to distinguish between multiple buttons on the same form. Only named buttons can be detected.

func (*ButtonWidget) Valid 

func (wgt *ButtonWidget) Valid(r *http.Request) bool

Valid validates the field's value against all validators.

func (*ButtonWidget) Value 

func (wgt *ButtonWidget) Value(r *http.Request) string

Value returns "1" if this named button was just pressed, "" otherwise. Disabled buttons always return "". Prefer Pressed for boolean checks.

func (*ButtonWidget) WithHref 

func (wgt *ButtonWidget) WithHref(href string) *ButtonWidget

WithHref turns the button into a link to href instead of a submit button. Accepts the full action-URL grammar (`?key=`, `^?…`, `/path`, etc.). Resets any prior WithHrefBack().

func (*ButtonWidget) WithHrefBack 

func (wgt *ButtonWidget) WithHrefBack() *ButtonWidget

WithHrefBack turns this into a "back" button. It follows the `_back` state variable when set; otherwise falls back to a browser-history back step if the referrer is the same host. The button auto-hides when there's no history to go back to. Set `_back=0` to force-disable.

func (*ButtonWidget) WithPredicate 

func (wgt *ButtonWidget) WithPredicate(predicate func(value string) (bool, string)) *ButtonWidget

WithPredicate attaches a custom validator that runs only when this button is pressed. The button must be named for press detection to work. Use this for cross-field validations that don't belong to any individual input — e.g. "either email or phone must be filled".

func (*ButtonWidget) WithTarget 

func (wgt *ButtonWidget) WithTarget(target string) *ButtonWidget

WithTarget sets the target of the button's link.

func (*ButtonWidget) WithWidth 

func (wgt *ButtonWidget) WithWidth(css string) *ButtonWidget

WithWidth scales the button to the given width. Pass any CSS length, e.g. "120px", "50%" or "calc(100% - 1em)". Empty clears it.

type BytesWidget 

type BytesWidget = widget.BytesWidget

type CheckboxWidget 

type CheckboxWidget struct {
	*widget.InputWidgetBase[*CheckboxWidget]
	// contains filtered or unexported fields
}

CheckboxWidget renders a Checkbox.

func (*CheckboxWidget) Add 

func (wgt *CheckboxWidget) Add(children ...any) *CheckboxWidget

Add adds nested widgets.

func (*CheckboxWidget) Changed 

func (wgt *CheckboxWidget) Changed(r *http.Request) bool

Changed indicates if the value of the field changed.

func (*CheckboxWidget) Checked 

func (wgt *CheckboxWidget) Checked(r *http.Request) bool

Checked reports whether the checkbox is currently checked, taking into account the user's input and the initial state.

func (*CheckboxWidget) Children 

func (wgt *CheckboxWidget) Children() []Widget

Children are the widgets nested under this widget.

func (*CheckboxWidget) Draw 

func (wgt *CheckboxWidget) Draw(w io.Writer, r *http.Request) (err error)

Draw renders the widget's HTML.

func (*CheckboxWidget) Valid 

func (wgt *CheckboxWidget) Valid(r *http.Request) bool

Valid validates the field's value against all validators.

func (*CheckboxWidget) Value 

func (wgt *CheckboxWidget) Value(r *http.Request) string

Value returns "1" when the checkbox is currently checked, "" otherwise. Prefer Checked for boolean reads.

func (*CheckboxWidget) WithPredicate 

func (wgt *CheckboxWidget) WithPredicate(predicate func(value string) (valid bool, errMsg string)) *CheckboxWidget

WithPredicate adds a custom validator. value is "1" when checked and "" otherwise; predicates run on both states. 

type DropdownWidget struct {
	*widget.InputWidgetBase[*DropdownWidget]
	// contains filtered or unexported fields
}

DropdownWidget renders a dropdown selector. 

func (wgt *DropdownWidget) AddDisabledOption(value string, caption string) *DropdownWidget

AddDisabledOption appends a non-selectable option — useful for section headers or otherwise-grey-out choices. Submitting a disabled option fails validation. 

func (wgt *DropdownWidget) AddOption(value string, caption string) *DropdownWidget

AddOption appends a selectable option. value is what gets posted; caption is shown to the user. Options appear in insertion order. 

func (wgt *DropdownWidget) Changed(r *http.Request) bool

Changed indicates if the value of the field changed. 

func (wgt *DropdownWidget) Draw(w io.Writer, r *http.Request) (err error)

Draw renders the widget's HTML. 

func (wgt *DropdownWidget) Valid(r *http.Request) bool

Valid validates the field's value against all validators. 

func (wgt *DropdownWidget) Value(r *http.Request) string

Value returns the value of the field. 

func (wgt *DropdownWidget) WithPredicate(predicate func(value string) (bool, string)) *DropdownWidget

WithPredicate adds a custom validator. Runs after the option-list check, so it always receives a value that exists in the options. 

func (wgt *DropdownWidget) WithStretch(stretch bool) *DropdownWidget

WithStretch makes the dropdown fill the available width. By default it's sized to its longest option label.

type FieldLabelWidget 

type FieldLabelWidget struct {
	*widget.WidgetBase[*FieldLabelWidget]
	// contains filtered or unexported fields
}

FieldLabelWidget renders a field label.

func (*FieldLabelWidget) Add 

func (wgt *FieldLabelWidget) Add(children ...any) *FieldLabelWidget

Add adds nested widgets.

func (*FieldLabelWidget) Children 

func (wgt *FieldLabelWidget) Children() []Widget

Children are the widgets nested under this widget.

func (*FieldLabelWidget) Draw 

func (wgt *FieldLabelWidget) Draw(w io.Writer, r *http.Request) (err error)

Draw renders the widget's HTML.

type FieldWidget 

type FieldWidget struct {
	*widget.WidgetBase[*FieldWidget]
	// contains filtered or unexported fields
}

FieldWidget renders a field of a form.

func (*FieldWidget) AddLeft 

func (wgt *FieldWidget) AddLeft(children ...any) *FieldWidget

AddLeft appends widgets to the field's label area.

func (*FieldWidget) AddRight 

func (wgt *FieldWidget) AddRight(children ...any) *FieldWidget

AddRight appends widgets to the field's body — typically the input control(s) and any inline hints.

func (*FieldWidget) Children 

func (wgt *FieldWidget) Children() []Widget

Children are the widgets nested under this widget.

func (*FieldWidget) Draw 

func (wgt *FieldWidget) Draw(w io.Writer, r *http.Request) (err error)

Draw renders the widget's HTML.

type Fields 

type Fields map[string]InputWidget

Fields are the input widgets posted with the form. The underlying structure is a map[string]InputWidget that can be iterated.

func (Fields) Get 

func (f Fields) Get(name string) (field InputWidget)

Get returns the named field.

func (Fields) Has 

func (f Fields) Has(name string) bool

Has indicates if the named field was posted with the form.

type FilterChipWidget 

type FilterChipWidget struct {
	*widget.InputWidgetBase[*FilterChipWidget]
	// contains filtered or unexported fields
}

FilterChipWidget renders a filter chip toggle.

func (*FilterChipWidget) Changed 

func (wgt *FilterChipWidget) Changed(r *http.Request) bool

Changed indicates if the value of the field changed.

func (*FilterChipWidget) Checked 

func (wgt *FilterChipWidget) Checked(r *http.Request) bool

Checked reports whether the chip is currently selected.

func (*FilterChipWidget) Draw 

func (wgt *FilterChipWidget) Draw(w io.Writer, r *http.Request) (err error)

Draw renders the widget's HTML.

func (*FilterChipWidget) Valid 

func (wgt *FilterChipWidget) Valid(r *http.Request) bool

Valid validates the field's value against all validators.

func (*FilterChipWidget) Value 

func (wgt *FilterChipWidget) Value(r *http.Request) string

Value returns "1" when the chip is selected, "" otherwise. Prefer Checked for boolean reads.

type FormFactory 

type FormFactory struct{}

FormFactory aggregates the widget constructors of this package. Use FormFactory{} to construct a new factory

func (FormFactory) Alert 

func (f FormFactory) Alert(name string, icon string, title string) *AlertWidget

Alert creates a new widget that renders a confirmation modal — a primary-coloured icon on the left next to a heading and action buttons. Like Modal, the alert opens when the named state variable is non-empty; the typical pattern is to set it to an ID (e.g. ?delete=42) from a list-row action. Pass icon="" for an icon-less alert. For an error-styled (red) icon, use AlertError.

func (FormFactory) AlertError 

func (f FormFactory) AlertError(name string, icon string, title string) *AlertWidget

AlertError is the error-styled variant of Alert — the icon is rendered in the theme's error color, suitable for destructive confirmations.

func (FormFactory) ButtonElevated 

func (f FormFactory) ButtonElevated(name string) *ButtonWidget

ButtonElevated creates a new Material elevated button — like ButtonText but with a slight shadow, used when the button needs to stand out from a busy background.

func (FormFactory) ButtonFilled 

func (f FormFactory) ButtonFilled(name string) *ButtonWidget

ButtonFilled creates a new high-emphasis Material button — use for the primary action of a form or screen. name is the field name posted on click; an empty name means the press isn't reported back via Pressed.

func (FormFactory) ButtonOutlined 

func (f FormFactory) ButtonOutlined(name string) *ButtonWidget

ButtonOutlined creates a new Material outlined button — medium emphasis, for actions paired with a primary filled button.

func (FormFactory) ButtonText 

func (f FormFactory) ButtonText(name string) *ButtonWidget

ButtonText creates a new Material text button — low emphasis, suitable for in-line and toolbar actions.

func (FormFactory) ButtonTonal 

func (f FormFactory) ButtonTonal(name string) *ButtonWidget

ButtonTonal creates a new Material tonal button — a softer alternative to ButtonFilled, used for secondary actions that still need visual weight.

func (FormFactory) Checkbox 

func (f FormFactory) Checkbox(name string, checked bool) *CheckboxWidget

Checkbox creates a new widget that renders a Material checkbox. name is the state variable; checked is the initial state. The posted value is "1" when checked and "" when not — read it via Checked. Pair with WithRequired to force the user to tick it (e.g. T&Cs).

func (FormFactory) Dropdown 

func (f FormFactory) Dropdown(name, value string) *DropdownWidget

Dropdown creates a new widget that renders a native <select>. Add choices via AddOption (or AddDisabledOption); insertion order is preserved. A blank choice is prepended automatically unless the field is required or already includes one. Submitted values that aren't in the options list fail validation. For a searchable dropdown, see RichDropdown.

func (FormFactory) Field 

func (f FormFactory) Field() *FieldWidget

Field creates a new widget that lays out one form row with a label on the left and the input(s) on the right. Use AddLeft for the label content and AddRight for the input. On narrow viewports the label stacks above the input.

func (FormFactory) FieldLabel 

func (f FormFactory) FieldLabel(children ...any) *FieldLabelWidget

FieldLabel creates a new widget for a styled form-label block. Field already wraps its left content in a FieldLabel — call this directly only when you're laying out a form by hand.

func (FormFactory) FilterChip 

func (f FormFactory) FilterChip(name string, label string, checked bool) *FilterChipWidget

FilterChip creates a new widget that renders a Material filter chip — a labelled on/off toggle styled as a chip. Posts "1" when on, "" otherwise. Group multiple chips inside a Gallery so they wrap nicely.

func (FormFactory) Form 

func (f FormFactory) Form() *FormWidget

Form creates a new widget that renders an input form. Defaults: POST to the current URL, autocomplete off, max-width 800px. Submission writes `_submit=<form name>` to state so the handler can detect it via Submitted or ReadyToCommit; nested input widgets attach to this form automatically when added via Form.Add.

func (FormFactory) InputChips 

func (f FormFactory) InputChips(name string, dataURL string) *InputChipsWidget

InputChips creates a new widget that renders a chips input. The data URL is an endpoint that responds with an array of options in response to a query in the form: 

GET dataURL?q=harry

The response is expected to JSON object with a single JSON array field "options". 

{
	"options": [
		{"title":"Harry Potter", "value":"12345678", "desc":"harry.potter@hogwarts.edu"},
		{"title":"Dirty Harry",  "value":"90909090", "desc":"dirty.harry@sfpd.gov"},
		...
	]
}

The first 8 options that are not already selected will be displayed in the dropdown. It is therefore recommended to return more than 8 results.

func (FormFactory) InputColor 

func (f FormFactory) InputColor(name string, value string) *InputTextWidget

InputColor creates a new widget for a hex color picker. value must be in lowercase #RRGGBB form, or empty.

func (FormFactory) InputDate 

func (f FormFactory) InputDate(name string, value time.Time) *InputTextWidget

InputDate creates a new widget for a date picker. Pass a zero time to leave the field empty. Adjust value into the user's time zone before passing it in — the field uses the raw Y-M-D from the value.

func (FormFactory) InputDecimal 

func (f FormFactory) InputDecimal(name string, value any, precision int) *InputTextWidget

InputDecimal creates a new widget for a fractional-number field. value may be a float64 or a pre-formatted string; anything else leaves the field empty. precision is the number of digits shown after the decimal point in the initial value.

func (FormFactory) InputEmail 

func (f FormFactory) InputEmail(name string, value string) *InputTextWidget

InputEmail creates a new widget for an email field with built-in RFC-5322 + simple TLD validation.

func (FormFactory) InputFile 

func (f FormFactory) InputFile(name string, fileName string, receiverURL string) *InputFileWidget

InputFile creates a new widget that renders a file selector. A non-empty filename indicates the current value of the widget.

The receiver is a web endpoint that the client can communicate with to upload the file. The endpoint must support the following API: 

POST path?name=filename.txt

Accepts the body of the first or only data chunk. It must return a JSON struct with a "key" property to identify the upload sequence: {"key":"123456"} 

POST path?key=123456

Accepts additional chunks to the upload sequence represented by the key. 

GET path?key=123456

Returns the consolidated chunks in the body of the message, and the file name in the Content-Disposition header. https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition

func (FormFactory) InputHidden 

func (f FormFactory) InputHidden(name string, value string) *InputHiddenWidget

InputHidden creates a new widget that renders a hidden form field — posted with the form but invisible to the user. Use this to carry an ID or context value through a submission. The value is fixed at construction; user input cannot change it.

func (FormFactory) InputInteger 

func (f FormFactory) InputInteger(name string, value any) *InputTextWidget

InputInteger creates a new widget for a whole-number field. value may be an int or a pre-formatted string; anything else leaves the field empty. Defaults to ~16 chars wide.

func (FormFactory) InputMonth 

func (f FormFactory) InputMonth(name string, value time.Time) *InputTextWidget

InputMonth creates a new widget for a year-month picker. Pass a zero time to leave the field empty. Adjust value into the user's time zone before passing it in.

func (FormFactory) InputOneTimePassword 

func (f FormFactory) InputOneTimePassword(name string, value string) *InputTextWidget

InputOneTimePassword creates a new widget for a one-time password code entry, styled with letter spacing for character-by-character readability. Combine with WithLength to fix the code length.

func (FormFactory) InputPassword 

func (f FormFactory) InputPassword(name string, value string) *InputTextWidget

InputPassword creates a new widget for a password field — masked input, no whitespace trimming.

func (FormFactory) InputPhone 

func (f FormFactory) InputPhone(name string, value string) *InputTextWidget

InputPhone creates a new widget for a phone-number field — same HTML type as InputTel, but with no built-in validator so any characters are accepted.

func (FormFactory) InputRange 

func (f FormFactory) InputRange(name string, value any) *InputTextWidget

InputRange creates a new widget for a slider that emits an integer. Use WithMin/WithMax to set the range and WithStep for the granularity. Stretches to fill its container.

func (FormFactory) InputTel 

func (f FormFactory) InputTel(name string, value string) *InputTextWidget

InputTel creates a new widget for a telephone number field. Validates against the IETF tel-dial-string characters (digits and , ; * # +). For an unvalidated tel field, use InputPhone.

func (FormFactory) InputText 

func (f FormFactory) InputText(name string, value string) *InputTextWidget

InputText creates a new widget that renders a single-line text input. name is the state variable the field reads/writes; value is the initial content (used until the user types something). Defaults: leading and trailing whitespace are trimmed, browser autocomplete is off, no length limits.

func (FormFactory) InputTime 

func (f FormFactory) InputTime(name string, value time.Time) *InputTextWidget

InputTime creates a new widget for a time-of-day picker. Pass a zero time to leave the field empty. Adjust value into the user's time zone before passing it in.

func (FormFactory) InputTimeZone 

func (f FormFactory) InputTimeZone(name string, value string) *InputTimeZoneWidget

InputTimeZone creates a new widget that renders a paired region / city dropdown for picking an IANA time zone name (e.g. "America/Los_Angeles"). value is the initial selection; pass "" for no preselection. Submitted values must match an entry in the bundled IANA name list to pass validation.

func (FormFactory) InputURL 

func (f FormFactory) InputURL(name string, value string) *InputTextWidget

InputURL creates a new widget for a URL field. A missing scheme is accepted (https:// is assumed for validation); the on-screen keyboard shows URL-friendly characters on mobile.

func (FormFactory) Radio 

func (f FormFactory) Radio(name string, value string) *RadioWidget

Radio creates a new widget that renders a group of radio buttons. name is the state variable; value is the option pre-selected on first render. Add choices via AddOption. Defaults to a vertical layout. A submitted value that matches none of the options fails validation.

func (FormFactory) RatingSentiment 

func (f FormFactory) RatingSentiment(name string, valueStars int) *RatingWidget

RatingSentiment creates a new widget that renders a 1-to-5 sentiment rating (very-dissatisfied → very-satisfied face icons). Same posting semantics as RatingStars. Pass 0 for "no rating yet".

func (FormFactory) RatingStars 

func (f FormFactory) RatingStars(name string, valueStars int) *RatingWidget

RatingStars creates a new widget that renders a 1-to-5 star rating input. valueStars is the initial selection (clamped to 0..5); pass 0 for "no rating yet". Posted as a decimal integer string.

func (FormFactory) RichDropdown 

func (f FormFactory) RichDropdown(name string, value string) *RichDropdownWidget

RichDropdown creates a new widget that renders a dropdown whose options can contain arbitrary widgets (icons, avatars, multi-line descriptions), not just text. Use AddOption to attach a value and its rendered body. For a plain text dropdown, use Dropdown instead.

func (FormFactory) Toggle 

func (f FormFactory) Toggle(name string, checked bool) *ToggleWidget

Toggle creates a new widget that renders a Material switch. Functionally identical to Checkbox (posts "1"/"") but visually represented as a sliding switch — prefer it for on/off settings rather than agree-to-terms cases.

type FormWidget 

type FormWidget struct {
	*widget.WidgetBase[*FormWidget]
	// contains filtered or unexported fields
}

FormWidget renders an input form.

func (*FormWidget) Add 

func (wgt *FormWidget) Add(children ...any) *FormWidget

Add appends children to the form. Buttons added at any position are automatically collected into a trailing toolbar (right-aligned), so you don't have to wrap them yourself. Input widgets in the subtree are linked to this form by name so Values/Fields/Submitted can find them.

func (*FormWidget) Changed 

func (wgt *FormWidget) Changed(r *http.Request) bool

Changed reports whether any field's posted value differs from its initial value. Returns false for unsubmitted or reset forms.

func (*FormWidget) Children 

func (wgt *FormWidget) Children() []Widget

Children are the widgets nested under this widget.

func (*FormWidget) Draw 

func (wgt *FormWidget) Draw(w io.Writer, r *http.Request) (err error)

Draw renders the widget's HTML.

func (*FormWidget) Drawn 

func (wgt *FormWidget) Drawn(r *http.Request) bool

Drawn indicates whether this widget needs to be drawn.

func (*FormWidget) Fields 

func (wgt *FormWidget) Fields(r *http.Request) map[string]InputWidget

Fields returns the visible InputWidgets currently nested in the form, keyed by field name. Hidden subtrees (HideIf*) are excluded — useful when validation should ignore fields the user can't see.

func (*FormWidget) ReadyToCommit 

func (wgt *FormWidget) ReadyToCommit(r *http.Request) bool

ReadyToCommit returns true when the user just submitted this form and every field passes validation — the typical guard around persisting values: 

if form.ReadyToCommit(r) { … persist … }

func (*FormWidget) Reset 

func (wgt *FormWidget) Reset(r *http.Request)

Reset clears every field's posted value so the form re-renders with its initial values. Call this after a successful save when you want to show a fresh empty form rather than the user's just-committed input.

func (*FormWidget) Submitted 

func (wgt *FormWidget) Submitted(r *http.Request) bool

Submitted returns true when the current request is a submission of this specific form (matched by HTTP method and the `_submit` state variable). Prefer ReadyToCommit, which also checks validation.

func (*FormWidget) Valid 

func (wgt *FormWidget) Valid(r *http.Request) bool

Valid runs every visible field's validator and returns true if all pass. Returns true for unsubmitted forms (nothing to validate yet). Validators run concurrently — safe for expensive custom predicates.

func (*FormWidget) Values 

func (wgt *FormWidget) Values(r *http.Request) Values

Values collects every nested input's current value, keyed by field name. Hidden inputs and inputs in hidden subtrees are included; use Fields if you need to inspect the InputWidgets themselves.

func (*FormWidget) WithAction 

func (wgt *FormWidget) WithAction(method string, action string) *FormWidget

WithAction sets the submit method and URL. Default is POST to "?", which writes the form's fields into the current page's state — the idiomatic choice. Use GET for query/search forms; POST for forms that persist data. Only "GET" and "POST" are accepted; other methods are silently ignored.

func (*FormWidget) WithAutoComplete 

func (wgt *FormWidget) WithAutoComplete(autoComplete string) *FormWidget

WithAutoComplete sets the form's HTML autocomplete attribute. Default is "off"; common alternative is "on". Use "" to let the browser inherit from the page. Individual text inputs can override via their own WithAutoComplete. See the HTML autocomplete spec for the full list of tokens.

func (*FormWidget) WithName 

func (wgt *FormWidget) WithName(name string) *FormWidget

WithName sets the form's name. The name is written into `_submit` on submission, which is how Submitted/ReadyToCommit discriminate between multiple forms on the same page. Default is "form".

func (*FormWidget) WithTarget 

func (wgt *FormWidget) WithTarget(target string) *FormWidget

WithTarget sets the HTML target for the form's submission. Defaults to the page's `_target` state variable when unset, so submissions route back to the active frame.

func (*FormWidget) WithWidth 

func (wgt *FormWidget) WithWidth(css string) *FormWidget

WithWidth caps the form's max-width. Default is 800px; the form still compresses below 600px regardless. Empty clears the cap. Pass any CSS length, e.g. "800px", "90%" or "calc(100vw - 2em)".

type InputChipsWidget 

type InputChipsWidget struct {
	*widget.InputWidgetBase[*InputChipsWidget]
	// contains filtered or unexported fields
}

InputChipsWidget renders a chips input.

func (*InputChipsWidget) AddChip 

func (wgt *InputChipsWidget) AddChip(value string, title string) *InputChipsWidget

AddChip seeds an initial chip. value is what gets posted; title is the visible label (defaults to value when empty). Call once per pre-selected item before Draw.

func (*InputChipsWidget) Changed 

func (wgt *InputChipsWidget) Changed(r *http.Request) bool

Changed indicates if the value of the field changed.

func (*InputChipsWidget) Draw 

func (wgt *InputChipsWidget) Draw(w io.Writer, r *http.Request) (err error)

Draw renders the widget's HTML.

func (*InputChipsWidget) Valid 

func (wgt *InputChipsWidget) Valid(r *http.Request) bool

Valid validates the field's value against all validators.

func (*InputChipsWidget) Value 

func (wgt *InputChipsWidget) Value(r *http.Request) string

Value returns the chips' values concatenated with "\n" separators. Split on "\n" to recover the individual chip values. Empty when no chips are present.

func (*InputChipsWidget) WithDedup 

func (wgt *InputChipsWidget) WithDedup(dedup bool) *InputChipsWidget

WithDedup drops duplicate values from the posted result. Default is false (duplicates allowed). Comparison is by chip value, not title.

func (*InputChipsWidget) WithLength 

func (wgt *InputChipsWidget) WithLength(minChars int, maxChars int) *InputChipsWidget

WithLength bounds the length of each individual chip's value, in characters. Pass a negative value for either bound to leave it unbounded. A non-zero minimum does not imply Required.

func (*InputChipsWidget) WithMaxItems 

func (wgt *InputChipsWidget) WithMaxItems(maxItems int) *InputChipsWidget

WithMaxItems caps the number of chips the user can add. Submitting more fails validation. 0 (default) means no limit.

func (*InputChipsWidget) WithPlaceholder 

func (wgt *InputChipsWidget) WithPlaceholder(placeholder string) *InputChipsWidget

WithPlaceholder sets the placeholder text of the field.

func (*InputChipsWidget) WithPredicate 

func (wgt *InputChipsWidget) WithPredicate(predicate func(value string) (bool, string)) *InputChipsWidget

WithPredicate checks the field's value against a predicate function. Predicates are run against empty fields as well.

func (*InputChipsWidget) WithWidth 

func (wgt *InputChipsWidget) WithWidth(css string) *InputChipsWidget

WithWidth sets the visible width. Pass any CSS length, e.g. "16ch", "200px" or "100%". Empty lets it fill the container — the default.

type InputFileWidget 

type InputFileWidget struct {
	*widget.InputWidgetBase[*InputFileWidget]
	// contains filtered or unexported fields
}

InputFileWidget renders a file selector.

func (*InputFileWidget) Changed 

func (wgt *InputFileWidget) Changed(r *http.Request) bool

Changed indicates if the value of the field changed.

func (*InputFileWidget) Draw 

func (wgt *InputFileWidget) Draw(w io.Writer, r *http.Request) (err error)

Draw renders the widget's HTML.

func (*InputFileWidget) Valid 

func (wgt *InputFileWidget) Valid(r *http.Request) bool

Valid validates the field's value against all validators.

func (*InputFileWidget) Value 

func (wgt *InputFileWidget) Value(r *http.Request) string

Value returns the value of the field.

func (*InputFileWidget) WithAccept 

func (wgt *InputFileWidget) WithAccept(types string) *InputFileWidget

WithAccept determines what file types are accepted by the widget. Types is a comma-separated list of any of the following: (1) A valid case-insensitive filename extension, starting with a period (".") character; (2) A valid MIME type string, with no extensions; (3) The string audio/* meaning "any audio file"; (4) The string video/* meaning "any video file"; (5) The string image/* meaning "any image file".

See https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept .

func (*InputFileWidget) WithMaxSize 

func (wgt *InputFileWidget) WithMaxSize(sizeBytes int) *InputFileWidget

WithMaxSize caps the upload size in bytes. Default is 64 MiB. Pass 0 (or a negative value) to remove the limit. Enforced client-side only — always re-validate at the receiver endpoint.

type InputHiddenWidget 

type InputHiddenWidget struct {
	*widget.InputWidgetBase[*InputHiddenWidget]
	// contains filtered or unexported fields
}

InputHiddenWidget renders a hidden input field.

func (*InputHiddenWidget) Changed 

func (wgt *InputHiddenWidget) Changed(r *http.Request) bool

Changed indicates if the value of the field changed.

func (*InputHiddenWidget) Draw 

func (wgt *InputHiddenWidget) Draw(w io.Writer, r *http.Request) (err error)

Draw renders the widget's HTML.

func (*InputHiddenWidget) Valid 

func (wgt *InputHiddenWidget) Valid(r *http.Request) bool

Valid validates the field's value against all validators.

func (*InputHiddenWidget) Value 

func (wgt *InputHiddenWidget) Value(r *http.Request) string

Value returns the value of the field.

type InputTextWidget 

type InputTextWidget struct {
	*widget.InputWidgetBase[*InputTextWidget]
	// contains filtered or unexported fields
}

InputTextWidget renders a textual input field.

func (*InputTextWidget) Changed 

func (wgt *InputTextWidget) Changed(r *http.Request) bool

Changed indicates if the value of the field changed.

func (*InputTextWidget) Draw 

func (wgt *InputTextWidget) Draw(w io.Writer, r *http.Request) (err error)

Draw renders the widget's HTML.

func (*InputTextWidget) Valid 

func (wgt *InputTextWidget) Valid(r *http.Request) bool

Valid validates the field's value against all validators.

func (*InputTextWidget) Value 

func (wgt *InputTextWidget) Value(r *http.Request) string

Value returns the field's effective value: the user's posted input when available, or the initial value otherwise. Trimmed (unless WithTrimSpaces(false)), clamped to WithMin/WithMax, and normalized for times (zero-second suffix). Disabled fields always return the initial value.

func (*InputTextWidget) WithAutoComplete 

func (wgt *InputTextWidget) WithAutoComplete(autoComplete string) *InputTextWidget

WithAutoComplete determines the browser's auto complete behavior of the field. See https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete for valid values. The common options are "on" and "off", with "off" being the default. Use the empty string "" to inherit the behavior of the parent form.

func (*InputTextWidget) WithAutoFocus 

func (wgt *InputTextWidget) WithAutoFocus(autoFocus bool) *InputTextWidget

WithAutoFocus automatically focuses the cursor on the text input field. Auto-focus is off by default.

func (*InputTextWidget) WithLength 

func (wgt *InputTextWidget) WithLength(minChars int, maxChars int) *InputTextWidget

WithLength bounds the field length to [minChars, maxChars] in characters. Pass a negative value for either bound to leave it unbounded. Note: a non-zero minimum does NOT make the field required on its own — pair with WithRequired if the field must be non-empty.

func (*InputTextWidget) WithMax 

func (wgt *InputTextWidget) WithMax(upperBound any) *InputTextWidget

WithMax sets an inclusive upper bound. Same type rules as WithMin. The current value is clamped to the new bound.

func (*InputTextWidget) WithMin 

func (wgt *InputTextWidget) WithMin(lowerBound any) *InputTextWidget

WithMin sets an inclusive lower bound. Pass an int for integer/range fields or a time.Time for date/month/time fields; types that don't match the field's HTML type are silently ignored. Adjust times into the user's time zone first. The current value is clamped to the new bound.

func (*InputTextWidget) WithMode 

func (wgt *InputTextWidget) WithMode(inputMode string) *InputTextWidget

WithMode sets the HTML `inputmode` attribute, hinting which on-screen keyboard mobile browsers should show (e.g. "decimal", "tel", "url", "email", "search", "numeric").

func (*InputTextWidget) WithPattern 

func (wgt *InputTextWidget) WithPattern(exp string) *InputTextWidget

WithPattern requires the value to match the given regexp. Applies to text/email/url/password/tel fields only; silently ignored for others. Pattern syntax is RE2 (Go's regexp) on the server; the browser uses its own engine for client-side hints.

func (*InputTextWidget) WithPlaceholder 

func (wgt *InputTextWidget) WithPlaceholder(placeholder string) *InputTextWidget

WithPlaceholder sets the placeholder text of the field.

func (*InputTextWidget) WithPredicate 

func (wgt *InputTextWidget) WithPredicate(predicate func(value string) (valid bool, errMsg string)) *InputTextWidget

WithPredicate adds a custom validator. Unlike the built-in validators, predicates are also called with an empty value — useful for required- like rules with custom messaging. The returned errMsg is shown to the user when valid is false.

func (*InputTextWidget) WithRows 

func (wgt *InputTextWidget) WithRows(rows int) *InputTextWidget

WithRows turns the field into a multi-line <textarea> of the given height. Default is 1 (single-line <input>). Multi-row fields skip client-side HTML validation — server-side validators still run.

func (*InputTextWidget) WithStep 

func (wgt *InputTextWidget) WithStep(granularity int) *InputTextWidget

WithStep constrains the value to multiples of granularity, measured from the field's initial value (or min if no initial value). Units: integer/range — units; time — seconds; date — days; month — months. Defaults: 1 for numbers/dates/months, 60 for time. Ignored for non- numeric/non-temporal fields.

func (*InputTextWidget) WithTrimSpaces 

func (wgt *InputTextWidget) WithTrimSpaces(trim bool) *InputTextWidget

WithTrimSpaces toggles leading/trailing whitespace trimming on the posted value. Default is true except for password fields, which are always preserved verbatim.

func (*InputTextWidget) WithWidth 

func (wgt *InputTextWidget) WithWidth(css string) *InputTextWidget

WithWidth sets the visible width of the field. Pass any CSS length, e.g. "16ch", "200px" or "100%". Empty lets it stretch to fill the container — the default.

type InputTimeZoneWidget 

type InputTimeZoneWidget struct {
	*widget.InputWidgetBase[*InputTimeZoneWidget]
	// contains filtered or unexported fields
}

InputTimeZoneWidget renders a time zone selector.

func (*InputTimeZoneWidget) Changed 

func (wgt *InputTimeZoneWidget) Changed(r *http.Request) bool

Changed indicates if the value of the field changed.

func (*InputTimeZoneWidget) Draw 

func (wgt *InputTimeZoneWidget) Draw(w io.Writer, r *http.Request) (err error)

Draw renders the widget's HTML.

func (*InputTimeZoneWidget) Valid 

func (wgt *InputTimeZoneWidget) Valid(r *http.Request) bool

Valid validates the field's value against all validators.

func (*InputTimeZoneWidget) Value 

func (wgt *InputTimeZoneWidget) Value(r *http.Request) string

Value returns the value of the field.

type InputWidget 

type InputWidget = widget.InputWidget

type Predicates 

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

Predicates is a chain of value-validating functions used internally by input widgets. App code typically attaches predicates via each input's WithPredicate method rather than constructing a Predicates directly. Results are memoized by value, so identical values are validated at most once per request.

func (*Predicates) Add 

func (p *Predicates) Add(predicate func(value string) (ok bool, errMsg string))

Add appends a predicate. nil predicates are skipped during Validate.

func (*Predicates) Validate 

func (p *Predicates) Validate(value string) (ok bool, errMsg string)

Validate runs each predicate in order against value, short-circuiting on the first failure and returning its error message. Returns (true, "") if every predicate passes (including the empty case).

type RadioWidget 

type RadioWidget struct {
	*widget.InputWidgetBase[*RadioWidget]
	// contains filtered or unexported fields
}

RadioWidget renders a radio button.

func (*RadioWidget) AddOption 

func (wgt *RadioWidget) AddOption(value string, caption string) *RadioWidget

AddOption appends a choice. value is what gets posted when selected; caption is the label shown to the user. Options render in insertion order.

func (*RadioWidget) Changed 

func (wgt *RadioWidget) Changed(r *http.Request) bool

Changed indicates if the value of the field changed.

func (*RadioWidget) Draw 

func (wgt *RadioWidget) Draw(w io.Writer, r *http.Request) (err error)

Draw renders the widget's HTML.

func (*RadioWidget) Valid 

func (wgt *RadioWidget) Valid(r *http.Request) bool

Valid validates the field's value against all validators.

func (*RadioWidget) Value 

func (wgt *RadioWidget) Value(r *http.Request) string

Value returns the value of the field.

func (*RadioWidget) WithHorizontal 

func (wgt *RadioWidget) WithHorizontal() *RadioWidget

WithHorizontal lays the radio buttons out in a row.

func (*RadioWidget) WithPredicate 

func (wgt *RadioWidget) WithPredicate(predicate func(value string) (valid bool, errMsg string)) *RadioWidget

WithPredicate adds a custom validator. value is the selected option's value, or "" if nothing is selected.

func (*RadioWidget) WithVertical 

func (wgt *RadioWidget) WithVertical() *RadioWidget

WithVertical stacks the radio buttons in a column. This is the default.

type RatingWidget 

type RatingWidget struct {
	*widget.InputWidgetBase[*RatingWidget]
	// contains filtered or unexported fields
}

RatingWidget renders a rating input widget.

func (*RatingWidget) Changed 

func (wgt *RatingWidget) Changed(r *http.Request) bool

Changed indicates if the value of the field changed.

func (*RatingWidget) Draw 

func (wgt *RatingWidget) Draw(w io.Writer, r *http.Request) (err error)

Draw renders the widget's HTML.

func (*RatingWidget) Valid 

func (wgt *RatingWidget) Valid(r *http.Request) bool

Valid validates the field's value against all validators.

func (*RatingWidget) Value 

func (wgt *RatingWidget) Value(r *http.Request) string

Value returns the value of the field.

type RichDropdownWidget 

type RichDropdownWidget struct {
	*widget.InputWidgetBase[*RichDropdownWidget]
	// contains filtered or unexported fields
}

RichDropdownWidget renders a rich dropdown selector.

func (*RichDropdownWidget) AddOption 

func (wgt *RichDropdownWidget) AddOption(value string, body ...any) *RichDropdownWidget

AddOption appends a choice. value is what gets posted when selected; body is the widget tree shown for this option (both in the closed dropdown and in the open list). Options render in insertion order.

func (*RichDropdownWidget) Changed 

func (wgt *RichDropdownWidget) Changed(r *http.Request) bool

Changed indicates if the value of the field changed.

func (*RichDropdownWidget) Draw 

func (wgt *RichDropdownWidget) Draw(w io.Writer, r *http.Request) (err error)

Draw renders the widget's HTML.

func (*RichDropdownWidget) Valid 

func (wgt *RichDropdownWidget) Valid(r *http.Request) bool

Valid validates the field's value against all validators.

func (*RichDropdownWidget) Value 

func (wgt *RichDropdownWidget) Value(r *http.Request) string

Value returns the value of the field.

type ToggleWidget 

type ToggleWidget struct {
	*widget.InputWidgetBase[*ToggleWidget]
	// contains filtered or unexported fields
}

ToggleWidget renders a switch toggle.

func (*ToggleWidget) Changed 

func (wgt *ToggleWidget) Changed(r *http.Request) bool

Changed indicates if the value of the field changed.

func (*ToggleWidget) Checked 

func (wgt *ToggleWidget) Checked(r *http.Request) bool

Checked reports whether the toggle is currently on.

func (*ToggleWidget) Draw 

func (wgt *ToggleWidget) Draw(w io.Writer, r *http.Request) (err error)

Draw renders the widget's HTML.

func (*ToggleWidget) Valid 

func (wgt *ToggleWidget) Valid(r *http.Request) bool

Valid validates the field's value against all validators.

func (*ToggleWidget) Value 

func (wgt *ToggleWidget) Value(r *http.Request) string

Value returns "1" when the toggle is on, "" when off. Prefer Checked for boolean reads.

type Values 

type Values map[string]string

Values are the values posted for all the widgets of the form. The underlying structure is a map[string]string that can be iterated.

func (Values) Get 

func (v Values) Get(name string) (value string)

Get returns the named value.

func (Values) Has 

func (v Values) Has(name string) bool

Has indicates if the named value was posted with the form.

type Widget 

type Widget = widget.Widget

Type aliases

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.