1.21.1 Procedures

Procedure: glyph-option KEY: #:value #:glyph #:content #:family #:selected-value #:disabled ¶

Construct an HTML option introduced by an inline glyph.

The glyph and the label are written as the option’s own text, because that is all an <option> may hold: a native dropdown is drawn by the browser or the operating system, which lays out the text of a row and ignores any element nested inside it. A glyph here is therefore a character or an emoji rather than an icon component, and it appears wherever the option is shown.

value

The value submitted when this option is chosen.

glyph

The character or emoji introducing the row, e.g. "🇳🇱".

content

The text of the row. Defaults to value.

family

List of symbols representing font family CSS classes for the option.

selected-value

The value the dropdown is currently showing.

disabled

A boolean marking the option as not choosable.

(glyph-option #:value "nl" #:glyph "🇳🇱" #:content "Nederlands")

Procedure: optgroup KEY: #:label #:options #:disabled ¶

Construct an HTML <optgroup>: a heading inside a menu.

A long menu reads as a list of headings rather than a list of rows once its options are grouped, and the group is the browser’s own idea rather than a class of ours – a native dropdown draws its header and indents the rows under it, so there is nothing in the companion stylesheet to go with this.

The label is the group’s whole purpose and the attribute is required by HTML; it is written when given, and omitted rather than written as #f when it is not, so a group with no heading is a group with no heading attribute rather than one claiming to be called #f.

A disabled group takes its rows out of play with it: none of them can be chosen, which is why a menu never states one of them as its selection.

label

The heading shown above the group’s rows.

options

List of option or glyph-option S-expressions making up the group.

disabled

A boolean disabling every row of the group at once.

(optgroup #:label "Europe"
          #:options (list (glyph-option #:value "nl" #:glyph "🇳🇱" #:content "Nederlands")
                          (glyph-option #:value "es" #:glyph "🇪🇸" #:content "Español")))

Procedure: option KEY: #:value #:content #:family #:selected-value #:disabled ¶

Construct an HTML <option> element.

The option is selected when its value names the selected-value, which is how a server-rendered page says which row a dropdown is showing. The two are compared as the text they are written as, so en_US and "en_US" are the same option; comparing them as Scheme values is how a selection goes missing between the server and the browser.

value

The value submitted when this option is chosen.

content

The text shown for the option. Defaults to value.

family

List of symbols representing font family CSS classes for the option.

selected-value

The value the dropdown is currently showing, so that the matching option renders as selected.

disabled

A boolean marking the option as not choosable, which is what a placeholder row such as a bare "Choose one..." wants.

(option #:value "light" #:content "Cozy Light Theme" #:selected-value "dark")

Procedure: select KEY: #:options #:on-change #:name #:id #:label #:help-text #:error #:required #:disabled #:family #:select-classes #:label-css #:select-flex-css ¶

Construct a dropdown list interactive selection menu wrapper.

The menu fills its container on phones and, from the small breakpoint up, takes the width it needs and no more: a row such as a flag beside a language name is shown whole, while a label long enough to matter stops at the edge of its container instead of pushing a narrow page sideways. A menu of a fixed width would instead clip the row it is showing, which is what min-content does to a control the browser draws itself.

Which row the menu shows is markup, not script: it is carried by the selected attribute of exactly one option, rendered from the selected-value the options were built with, so the field a reader sees is the field that is submitted. A menu whose rows match nothing – a stale value, or a hand-built list – gets its first choosable row marked, because that is the row the browser would display regardless.

A label is bound to the control through for whenever the menu has a name or an id to bind to, and help-text and error are linked by aria-describedby the same way, so the description of a field reaches assistive technology with it. Give the menu a name (the normal case for a form) and both bindings come for free.

The rows are a flat list, or groups of them: an optgroup entry stands in the list beside the options and holds rows of its own, which is how a long menu is read as a handful of headings instead of one run of rows.

options

A list of option, glyph-option or optgroup S-expressions making up the menu.

on-change

A string JavaScript execution statement evaluated during interaction changes.

name

The element name context configuration string bound onto target HTML form tracking.

id

The unique DOM string selector matching layout identifier tables; defaults to name for binding the label and the description.

label

The text introducing the field, rendered as a <label> bound to the control.

help-text

Optional helper copy rendered below the field and linked with aria-describedby.

error

Optional validation message rendered below the field with role="alert".

required

A boolean making the browser refuse to submit an empty menu.

disabled

A boolean disabling the control.

family

List of symbols representing base structural font choices.

select-classes

List of symbols specifying visual layout styles for the component wrapper card.

label-css

List of symbols representing presentation utility CSS classes for the label.

select-flex-css

List of symbols regulating structure container box margins and gaps.

(select #:label "Plan"
        #:name 'plan
        #:options (list (option #:value "cozy" #:content "Cozy (free)"
                                #:selected-value "cozy")
                        (option #:value "calm" #:content "Calm"))
        #:on-change "console.log('Changed!')")