Documentation
¶
Overview ¶
Package form provides type-safe form handling with validation for Vango applications.
Deprecated: The v1 Developer Guide expects form usage via `setup.Form` and `vango` re-exports. This package is retained for legacy/internal use only.
Overview ¶
The form package provides a generic Form[T] type that binds to Go structs, offering declarative validation through struct tags and built-in validators.
Basic Usage ¶
type ContactForm struct {
Name string `form:"name" validate:"required,min=2,max=100"`
Email string `form:"email" validate:"required,email"`
Message string `form:"message" validate:"required,max=1000"`
}
func ContactPage(p vango.NoProps) vango.Component {
return vango.Setup(p, func(s vango.SetupCtx[vango.NoProps]) vango.RenderFn {
form := setup.Form(&s, ContactForm{})
submit := func() {
if !form.Validate() {
return // Errors displayed automatically
}
data := form.Values()
sendEmail(data.Name, data.Email, data.Message)
form.Reset()
}
return func() *vango.VNode {
return Form(OnSubmit(submit),
form.Field("Name", Input(Type("text"))),
form.Field("Email", Input(Type("email"))),
form.Field("Message", Textarea()),
Button(Type("submit"), Text("Send")),
)
}
})
}
Validation ¶
The package includes built-in validators for common patterns:
- Required: Non-empty value
- MinLength/MaxLength: String length constraints
- Email: Valid email format
- Pattern: Regular expression matching
- Min/Max: Numeric range constraints
- Custom: User-defined validation logic
Form Arrays ¶
For forms with dynamic arrays of nested objects, use the Array method:
form.Array("Items", func(item FormArrayItem, i int) *vango.VNode {
return Div(
item.Field("Name", Input(Type("text"))),
Button(OnClick(item.Remove), Text("Remove")),
)
})
Index ¶
- func DecodeFormValues(values map[string][]string, dst any) error
- type AsyncValidator
- type EqualToField
- type Form
- func (f *Form[T]) AddValidators(field string, validators ...Validator)
- func (f *Form[T]) AppendTo(field string, value any)
- func (f *Form[T]) Array(field string, fn func(item FormArrayItem, index int) *vdom.VNode) *vdom.VNode
- func (f *Form[T]) ArrayKeyed(field string, keyFn func(item any) any, ...) *vdom.VNode
- func (f *Form[T]) ArrayLen(field string) int
- func (f *Form[T]) ClearErrors()
- func (f *Form[T]) ClearParseErrors()
- func (f *Form[T]) Errors() map[string][]string
- func (f *Form[T]) Field(name string, input *vdom.VNode, validators ...Validator) *vdom.VNode
- func (f *Form[T]) FieldDirty(field string) bool
- func (f *Form[T]) FieldErrors(field string) []string
- func (f *Form[T]) FieldParseError(field string) string
- func (f *Form[T]) Get(field string) any
- func (f *Form[T]) GetBool(field string) bool
- func (f *Form[T]) GetInt(field string) int
- func (f *Form[T]) GetString(field string) string
- func (f *Form[T]) HasError(field string) bool
- func (f *Form[T]) InsertAt(field string, index int, value any)
- func (f *Form[T]) IsDirty() bool
- func (f *Form[T]) IsSubmitting() bool
- func (f *Form[T]) IsTouched(field string) bool
- func (f *Form[T]) IsValid() bool
- func (f *Form[T]) ParseErrors() map[string]string
- func (f *Form[T]) RemoveAt(field string, index int)
- func (f *Form[T]) Reset()
- func (f *Form[T]) Set(field string, value any)
- func (f *Form[T]) SetError(field string, msg string)
- func (f *Form[T]) SetParseError(field string, msg string)
- func (f *Form[T]) SetSubmitting(submitting bool)
- func (f *Form[T]) SetValues(values T)
- func (f *Form[T]) Validate() bool
- func (f *Form[T]) ValidateField(field string) bool
- func (f *Form[T]) Values() T
- type FormArrayItem
- type NotEqualToField
- type ParseErrors
- type ValidationError
- type Validator
- func Alpha(msg string) Validator
- func AlphaNumeric(msg string) Validator
- func Between(min, max any, msg string) Validator
- func Custom(fn func(value any) error) Validator
- func DateAfter(t time.Time, msg string) Validator
- func DateBefore(t time.Time, msg string) Validator
- func Email(msg string) Validator
- func Future(msg string) Validator
- func Max(n any, msg string) Validator
- func MaxLength(n int, msg string) Validator
- func Min(n any, msg string) Validator
- func MinLength(n int, msg string) Validator
- func NonNegative(msg string) Validator
- func Numeric(msg string) Validator
- func Past(msg string) Validator
- func Pattern(pattern string, msg string) Validator
- func Phone(msg string) Validator
- func Positive(msg string) Validator
- func Required(msg string) Validator
- func URL(msg string) Validator
- func UUID(msg string) Validator
- type ValidatorFunc
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type AsyncValidator ¶
type AsyncValidator struct {
// contains filtered or unexported fields
}
AsyncValidator wraps an async validation function. The function returns (error, isComplete).
func Async ¶
func Async(fn func(value any) (error, bool)) *AsyncValidator
Async creates an async validator for server-side checks.
func (*AsyncValidator) IsComplete ¶
func (a *AsyncValidator) IsComplete() bool
IsComplete returns true if the async validation has completed.
func (*AsyncValidator) IsLoading ¶
func (a *AsyncValidator) IsLoading() bool
IsLoading returns true if the async validation is in progress.
func (*AsyncValidator) Validate ¶
func (a *AsyncValidator) Validate(value any) error
type EqualToField ¶
EqualToField creates a validator that checks if the value equals another field. Note: This validator needs form context, so it's typically added via Form.AddValidators.
func EqualTo ¶
func EqualTo(field string, msg string) *EqualToField
EqualTo returns a validator factory function. The actual comparison happens when the form is validated.
func (*EqualToField) SetForm ¶
func (e *EqualToField) SetForm(form interface{ Get(string) any })
SetForm sets the form context for comparison validators.
func (*EqualToField) Validate ¶
func (e *EqualToField) Validate(value any) error
type Form ¶
type Form[T any] struct { // contains filtered or unexported fields }
Form is a type-safe form handler with validation support. It provides reactive form state management, field-level validation, and automatic binding to Go structs via struct tags.
func SetupForm ¶
SetupForm creates a new Form bound to the given struct type during Setup. Signals are allocated during setup using the setup helpers.
func (*Form[T]) AddValidators ¶
AddValidators adds validators for a field. This allows adding validators programmatically instead of via struct tags.
func (*Form[T]) Array ¶
func (f *Form[T]) Array(field string, fn func(item FormArrayItem, index int) *vdom.VNode) *vdom.VNode
Array renders items in a form array using the provided render function. Each item is passed a FormArrayItem for accessing its fields.
func (*Form[T]) ArrayKeyed ¶
func (f *Form[T]) ArrayKeyed(field string, keyFn func(item any) any, fn func(item FormArrayItem, index int) *vdom.VNode) *vdom.VNode
ArrayKeyed renders items in a form array using RangeKeyed for stable identity. The key function must return a stable key for each item.
func (*Form[T]) ClearErrors ¶
func (f *Form[T]) ClearErrors()
ClearErrors removes all validation errors.
func (*Form[T]) ClearParseErrors ¶
func (f *Form[T]) ClearParseErrors()
ClearParseErrors removes all parse errors.
func (*Form[T]) Field ¶
Field wraps an input element with value binding and error display. It automatically binds the input value to the form field and shows errors.
The input's oninput and onblur handlers are chained (not replaced) if they exist. Handler signature is func(string) for the input value.
func (*Form[T]) FieldDirty ¶
FieldDirty returns true if the specific field has been modified.
func (*Form[T]) FieldErrors ¶
FieldErrors returns validation errors for a specific field.
func (*Form[T]) FieldParseError ¶
FieldParseError returns the parse error for a specific field.
func (*Form[T]) Get ¶
Get returns the value of a single field by name. Supports dot notation for nested fields (e.g., "address.city").
func (*Form[T]) IsSubmitting ¶
IsSubmitting returns true if the form is currently being submitted.
func (*Form[T]) ParseErrors ¶
ParseErrors returns all parse errors keyed by field name.
func (*Form[T]) Reset ¶
func (f *Form[T]) Reset()
Reset restores the form to its initial values and clears errors.
func (*Form[T]) SetParseError ¶
SetParseError manually sets a parse error message for a field.
func (*Form[T]) SetSubmitting ¶
SetSubmitting sets the submitting state.
func (*Form[T]) SetValues ¶
func (f *Form[T]) SetValues(values T)
SetValues replaces all form values with the given struct.
func (*Form[T]) Validate ¶
Validate runs all validators and returns true if the form is valid. Validation errors are stored and can be accessed via Errors() or FieldErrors().
func (*Form[T]) ValidateField ¶
ValidateField validates a single field and returns true if valid.
type FormArrayItem ¶
type FormArrayItem struct {
// contains filtered or unexported fields
}
FormArrayItem represents an item in a form array. It provides field access scoped to the array element's path.
func (FormArrayItem) Field ¶
Field wraps an input for an array item field. The path is automatically prefixed with the item's path.
func (FormArrayItem) Index ¶
func (i FormArrayItem) Index() int
Index returns the zero-based index of this item in the array.
func (FormArrayItem) Path ¶
func (i FormArrayItem) Path() string
Path returns the full path to this item (e.g., "Items.0").
func (FormArrayItem) Remove ¶
func (i FormArrayItem) Remove() func()
Remove removes this item from the array. Returns a function suitable for use with OnClick.
type NotEqualToField ¶
type NotEqualToField struct {
Field string
Message string
// contains filtered or unexported fields
}
NotEqualToField creates a validator that checks if the value differs from another field.
func NotEqualTo ¶
func NotEqualTo(field string, msg string) *NotEqualToField
NotEqualTo returns a validator that ensures the value differs from another field.
func (*NotEqualToField) SetForm ¶
func (e *NotEqualToField) SetForm(form interface{ Get(string) any })
func (*NotEqualToField) Validate ¶
func (e *NotEqualToField) Validate(value any) error
type ParseErrors ¶
ParseErrors represents per-field parse errors.
func (ParseErrors) Error ¶
func (p ParseErrors) Error() string
type ValidationError ¶
ValidationError represents a validation failure.
func (ValidationError) Error ¶
func (e ValidationError) Error() string
type Validator ¶
type Validator interface {
// Validate checks if the value is valid.
// Returns nil if valid, or an error with a message if invalid.
Validate(value any) error
}
Validator is an interface for form field validation.
func AlphaNumeric ¶
AlphaNumeric validates that the value contains only letters and digits.
func DateBefore ¶
DateBefore validates that a date/time is before the given time.
func NonNegative ¶
NonNegative validates that a numeric value is >= 0.
type ValidatorFunc ¶
ValidatorFunc is a function that implements Validator.
func (ValidatorFunc) Validate ¶
func (f ValidatorFunc) Validate(value any) error
Source Files