{"slug":"field","name":"Field","category":"Form & Input","summary":"Labels a custom control and renders its helper or error message.","status":"stable","since":"0.2.0","import":"import { Field } from '@elluzion/iv-ui';","usage":["Wrap one control; `htmlFor` must match the control id to associate the label.","`error` replaces `helper` and reuses the message id from `messageId` or `htmlFor`.","Built-in controls such as `Input` already render a label; use `Field` for custom form elements."],"props":[{"name":"label","type":"string","default":"''","description":"Label text associated with the control.","required":false,"bindable":false},{"name":"htmlFor","type":"string","default":"''","description":"Id of the control to label. Generated when omitted.","required":false,"bindable":false},{"name":"required","type":"boolean","default":"false","description":"Marks the field as required.","required":false,"bindable":false},{"name":"error","type":"string","default":"''","description":"Error message; replaces the helper text.","required":false,"bindable":false},{"name":"helper","type":"string","default":"''","description":"Helper text shown below the control.","required":false,"bindable":false},{"name":"messageId","type":"string","default":"''","description":"Id used for the message element referenced by `aria-describedby`.","required":false,"bindable":false},{"name":"className","type":"string","default":"''","description":"Extra classes merged onto the root element.","required":false,"bindable":false}],"events":[],"snippets":[{"name":"children","type":"Snippet","default":null,"description":"The control being labelled.","required":true,"bindable":false}],"types":[],"manual":[],"tokens":["--iv_error","--iv_font-ui","--iv_foreground","--iv_foreground-dim","--iv_leading-base","--iv_spacing-2xs","--iv_spacing-sm","--iv_spacing-xs","--iv_text-label","--iv_text-sm","--iv_weight-medium"],"cssHooks":["iv-field","iv-field-control","iv-field-error","iv-field-helper","iv-field-label","iv-field-message","iv-required-mark"],"accessibility":{"notes":["The label is a real `<label>` when `htmlFor` is set.","The message element gets an id so controls can reference it with `aria-describedby`.","Required fields show a visual asterisk that is hidden from assistive technology; set `required` on the control as well."]},"related":[{"title":"Input","summary":"A single-line text field with an optional label, helper, and error state.","url":"/components/input","kind":"Component"},{"title":"Textarea","summary":"A multi-line text field with an optional count and error state.","url":"/components/textarea","kind":"Component"},{"title":"Select","summary":"A custom listbox with search, multiple selection, and clearing.","url":"/components/select","kind":"Component"},{"title":"Checkbox","summary":"A binary choice with an optional label and a mixed state.","url":"/components/checkbox","kind":"Component"}],"examples":[{"id":"basic","title":"Basic","description":"A label, a native control, and helper text.","code":"<script lang=\"ts\">\n\timport { Field } from '@elluzion/iv-ui';\n</script>\n\n<div class=\"field-row\">\n\t<Field label=\"Project name\" htmlFor=\"field-basic\" helper=\"Shown in the project switcher.\">\n\t\t<input id=\"field-basic\" class=\"native\" placeholder=\"Orbital\" />\n\t</Field>\n</div>\n\n<style>\n\t.field-row {\n\t\twidth: 100%;\n\t\tmax-width: 320px;\n\t}\n\n\t.native {\n\t\twidth: 100%;\n\t\tbox-sizing: border-box;\n\t\tpadding: var(--iv_control-pad-y) var(--iv_control-pad-x);\n\t\tborder: 1px solid var(--iv_border);\n\t\tborder-radius: var(--iv_radius-sm);\n\t\tbackground: var(--iv_surface-raised);\n\t\tcolor: var(--iv_foreground);\n\t\tfont-family: var(--iv_font-ui);\n\t\tfont-size: var(--iv_text-body);\n\t}\n\n\t.native:focus-visible {\n\t\toutline: var(--iv_outline-width) solid var(--iv_foreground);\n\t\toutline-offset: 1px;\n\t}\n</style>"},{"id":"validation","title":"Validation","description":"The error message takes the place of the helper.","code":"<script lang=\"ts\">\n\timport { Field } from '@elluzion/iv-ui';\n\n\tlet slug = $state('');\n\tconst error = $derived(slug.length === 0 ? 'A slug is required.' : '');\n</script>\n\n<div class=\"field-row\">\n\t<Field\n\t\tlabel=\"Slug\"\n\t\thtmlFor=\"field-validation\"\n\t\trequired\n\t\t{error}\n\t\thelper=\"Lowercase letters, numbers, and dashes.\"\n\t>\n\t\t<input id=\"field-validation\" class=\"native\" bind:value={slug} placeholder=\"orbital\" />\n\t</Field>\n</div>\n\n<style>\n\t.field-row {\n\t\twidth: 100%;\n\t\tmax-width: 320px;\n\t}\n\n\t.native {\n\t\twidth: 100%;\n\t\tbox-sizing: border-box;\n\t\tpadding: var(--iv_control-pad-y) var(--iv_control-pad-x);\n\t\tborder: 1px solid var(--iv_border);\n\t\tborder-radius: var(--iv_radius-sm);\n\t\tbackground: var(--iv_surface-raised);\n\t\tcolor: var(--iv_foreground);\n\t\tfont-family: var(--iv_font-ui);\n\t\tfont-size: var(--iv_text-body);\n\t}\n\n\t.native:focus-visible {\n\t\toutline: var(--iv_outline-width) solid var(--iv_foreground);\n\t\toutline-offset: 1px;\n\t}\n</style>"},{"id":"custom-control","title":"Custom control","description":"The label is associated through `htmlFor`.","code":"<script lang=\"ts\">\n\timport { Field } from '@elluzion/iv-ui';\n\n\tlet color = $state('#b08d57');\n</script>\n\n<div class=\"field-row\">\n\t<Field label=\"Cursor accent\" htmlFor=\"field-color\" helper=\"Used for carets and active markers.\">\n\t\t<input id=\"field-color\" class=\"native color\" type=\"color\" bind:value={color} />\n\t</Field>\n\t<code class=\"readout\">{color}</code>\n</div>\n\n<style>\n\t.field-row {\n\t\tdisplay: flex;\n\t\talign-items: end;\n\t\tgap: var(--iv_spacing-lg);\n\t\twidth: 100%;\n\t\tmax-width: 360px;\n\t}\n\n\t.native {\n\t\twidth: 100%;\n\t\tbox-sizing: border-box;\n\t\tpadding: var(--iv_control-pad-y) var(--iv_control-pad-x);\n\t\tborder: 1px solid var(--iv_border);\n\t\tborder-radius: var(--iv_radius-sm);\n\t\tbackground: var(--iv_surface-raised);\n\t\tcolor: var(--iv_foreground);\n\t\tfont-family: var(--iv_font-ui);\n\t\tfont-size: var(--iv_text-body);\n\t}\n\n\t.color {\n\t\theight: var(--iv_control-md);\n\t\tpadding: var(--iv_spacing-2xs);\n\t}\n\n\t.readout {\n\t\tfont-family: var(--iv_font-mono);\n\t\tfont-size: var(--iv_text-sm);\n\t\tcolor: var(--iv_foreground-dim);\n\t}\n</style>"}],"markdown":"/components/field.md","page":"/components/field"}