Iridium

Appearance

Fields ​

Fields are the specific components that allow you define & set values for different elements.

Iridium includes the following for you:

Common Functions ​

Components share a set of similar functions that can be applied to any one.

Label ​

Set the label of your component.

Labels automatically convert the first letter of words to uppercase and add spaces where underscores are. For example, last_name is auto converted to the label Last Name

go
// static
FormInput("Name").
    Label("Your Name")

// callback
FormInput("Name").
    LabelFn(
        LabelFn(func(ctx *ctxPage.Field[T]) string {
            return "Your Name"
        }
    )

Inline ​

Inline allows you to place the Label of your form component in-line with the component itself, rather than ontop.

go
// static
FormInput("Name").
    Inline()

// callback
FormInput("Name").
    InlineFn(func(ctx *ctxPage.Field[T]) bool {
        return true
    })

DefaultValue ​

Set the default value of your component when the form is hydrated.

go
// static
FormInput("Name").
    DefaultValue("Joe Smith")

// callback
FormInput("Name").
    DefaultValueFn(
        func(ctx *ctxPage.Field[T]) string {
            return "Harry smith"
        }
    )

DefaultArrValue ​

DefaultArrValue allows you to set a series of default values for components that have multiple values, like the Select in Multiple mode.

go
// static
FormSelect("Name").
    DefaultArrValue([]string{"1","5"}) // select option with id 1 & 5
    
// callback
FormSelect("Name").
    DefaultArrValueFn(func(ctx *ctxPage.Field[T]) []string {
        return []string{"1","5"} // select option with id 1 & 5
    })

Disabled ​

The disable method will disable your input & prevent users from entering values.

WARNING

Disabled is front-end validation. It simply adds the disabled html element to your <input/>.

A skilled user can absolutely sidestep this & submit a value. Please remember to add the Prohibited rule to enforce this item is not edited on the server side.

go
// static
FormInput("Name").
    Disabled()

// callback
FormInput("Name").
    DisabledFn( 
        func(func(ctx *ctxPage.Field[T]) bool {
            return false
        }
    )

ReadOnly ​

ReadOnly applies the readonly attribute to your component.

go
// static
FormInput("Name").
    ReadOnly()
    
// callback
FormInput("Name").
    ReadOnlyFn(func(ctx *ctxPage.Field[T]) bool {
        return true
    })

Column Span ​

Each form component is placed inside a tailwind grid. You're able to define how many columns your component takes up with the ColumnSpan, ColumnSpanFn, ColumnSpanFixed, ColumnSpanFixedFn, & ColumnSpanFull or ColumnSpanFullFn

ColumnSpanFixed ​

go
// static
FormInput("Name").
    ColumnSpanFixed(2)

// callback
FormInput("Name").
    ColumnSpanFixedFn(func (ctx *ctxPage.Field[T]) int {
        return 2;
    })

ColumnSpan ​

You can customize the sizing of your elements by providing a map of columns to your component. This allows tailwind to natively resize your component based on your user's view port. Our tailwind config supports up to columns sizes of 12.

INFO

The column span applies tailwinds' col-span-X attribute to a containing div for your element. Each col-span-X divs need a containing div with a grid-cols-X method in order to render properly. Tailwind reference

Iridium forms default to a 2 grid columns setup. To change this grid size, please see our form documentation.

go
FormInput("Name").
    ColumnSpan(map[string]int{
        "xs": 2,
        "sm": 3,
        "md": 4,
        "lg": 5,
        "xl": 6,
    })

// callback function
FormInput("Name").
    ColumSpanFn(func (ctx *ctxPage.Field[T]) map[string]int {
        return map[string]int {
            "xs": 2,
            "sm": 3,
            "md": 4,
            "lg": 5,
            "xl": 6,
        }
    })

This will apply the relevant tailwind column sizes as so col-span-2 sm:col-span-3 and so forth to your components grid div.

ColumnSpanFull ​

You can easily expand your components to take an entire grid row using ColumnSpanFull or ColumnSpanFullFn

go
// fixed
FormInput("Name").
    ColumnSpanFull() // sets full span to `true`

// callback
FormInput("Name").
    ColumnSpanFullFn(func (ctx *ctxPage.Field[T]) bool{
        return true;
    })

ColumnSpanFull ignores any other column span methods. If you dynamically set the ColumnSpanFull to false, you can still define the span using any other method in this section.

Live ​

Live will apply live attributes to your field which allows it to reactively trigger this field's AfterStateUpdated method.

go
FormInput("Name").
    Live()

Live does nothing if not used alongside AfterStateUpdated

AfterStateUpdated ​

AfterStateUpdated is a callback that will be triggered whenever a field marked Live is interacted with, or during reactivity chains.

go
FormInput("Name").
    AfterStateUpdated(func(state []string, ctx *ctxPage.Field[models.User]) ([]string, error) {
        // can perform operations here if a user interacted with this field on the form
    }),

DebounceMs ​

DebounceMs applies a millisecond debounce for triggering Live integration on certain fields. Fields that can be changed instantly like toggles, selects, etc. do not have debounced applied.

go
FormInput("Name").
    Live().
    DebounceMs(250) // Trigger Live after 250ms of no interaction

Debounce does nothing if not used alongside Live

Rules ​

Rules allows you to provide a list of validation rules your form must pass in order to be submitted.

go
FormInput("Name").
    Rules(
        RuleAscii(),
        RuleRequired(),
        RuleStartsWith("Joe"),
    )

Required ​

An alias for the RuleRequired as part of our validation section.

Will add the Required rule to your component, which requires a non-empty string to pass validation. This will also mark your field with a red asteriks.

go
// static
FormInput("Name").
    Required()

// callback
FormInput("Name").
    RequiredFn(
        func(ctx *ctxPage.Field[T]) bool {
            return false
        }
    )

Attributes ​

Please see our attributes section for additional details.

Apply any number of attributes to your <input/> tag using the Attributes or AttributesFn method on your component.

Example ​

Here I am making the input log the word hello whenever it is clicked using Alpine.js.

go
// static
FormInput("Name").
    Attributes(map[string]any{
        "@click": "console.log('hello')",
    })

// callback
FormInput("Name").
    AttributesFn(func (ctx *ctxPage.Field[T]) map[string]any {
        if ctx.HasModel() {
            return map[string]any {
                "disabled": true,
            }
        } else {
            return map[string]any {
                "disabled": false, // Could also be removed.
            }
        }
    })

MutateStateBeforeFill ​

MutateStateBeforeFill allows you to change the state of the component before it is hydrated.

go
FormInput("Name").
    MutateStateBeforeFill(func(state []string, ctx *ctxPage.Field[T]) ([]string, error) {
        // Force an upper case before hydration
    	if len(state) == 1 {
    	    return []string{strings.ToUpper(state[0])}, nil
    	}
    	return state, nil
    }),

This applies during the form's lifecycle

MutateStateBeforeValidate ​

MutateStateBeforeValidate allows you to change the state of the component just before it is validated against its rules.

go
FormInput("Name").
    MutateStateBeforeValidate(func(state []string, ctx *ctxPage.Field[models.User]) ([]string, error) {
        // Force an upper case before validation
    	if len(state) == 1 {
    	    return []string{strings.ToUpper(state[0])}, nil
    	}
    	return state, nil		
    }),

This applies during the form's lifecycle

Released under the MIT License.

Copyright © 2025-present August Sosick