IconField

Search boxes and filter fields.

<sui-icon-field>Text inputsStable

About

Input with a Font Awesome icon before the text, after it or both: the toolbar search and filter pattern. Bare by default, so set aria-label and no label; add label, help or error when it sits in a form instead. clearable adds an X that empties the field. Form-associated: it posts name=value.

Usage

<sui-icon-field icon="fa-solid fa-magnifying-glass" name="q" placeholder="Search invoices" aria-label="Search invoices"></sui-icon-field> <script type="module"> import { defineCustomElements } from "@shineui/core/loader"; import "@shineui/core/shineui.css"; defineCustomElements(); const el = document.querySelector("sui-icon-field"); el.addEventListener("suiChange", (e) => console.log(e.detail)); </script>

import { SuiIconField } from "@shineui/react"; import "@shineui/core/shineui.css"; export function Example() { return <SuiIconField icon="fa-solid fa-magnifying-glass" name="q" placeholder="Search invoices" aria-label="Search invoices" onSuiChange={(e) => console.log(e.detail)} />; }

import { Component } from "@angular/core"; import { SuiIconField } from "@shineui/angular"; @Component({ standalone: true, imports: [SuiIconField], template: `<sui-icon-field icon="fa-solid fa-magnifying-glass" name="q" placeholder="Search invoices" aria-label="Search invoices" (suiChange)="onChange($event)"></sui-icon-field>`, }) export class Example { onChange(e: CustomEvent) { console.log(e.detail); } }

Basic

There is no visible label, so aria-label on the element names the field; without one the placeholder does. Icons are decoration and hidden from screen readers.

Sizes

md is the default, on the toolbar and in a form alike, one height with every other field; sm packs into table rows and lg is the roomier field for a sign-in or marketing page.

Clearable and states

The X shows only while there is a value. A read-only field keeps its value selectable and drops the X: that is the one edit it must refuse.

A hint in the end slot

The end slot sits inside the field's edge after the clear control and the trailing icon, and the input gives up room for it only while it is filled. A press on the hint puts the caret in the input, so the key reads as part of the field; a small action in the slot keeps its own click.

USD

In a form

Bare, so the browser bubble is the message surface and the aria-label names it. An empty field posts an empty string. Give the field a label and the message surface moves onto the page, which is the example below.

<form id="if-form" style="display:flex;gap:8px;align-items:center;flex-wrap:wrap;max-width:420px"> <sui-icon-field icon="fa-solid fa-magnifying-glass" name="q" required aria-label="Search invoices" placeholder="Search invoices" style="flex:1"></sui-icon-field> <sui-button type="submit" variant="brand" label="Search"></sui-button> <output id="if-out" style="flex-basis:100%;font:460 13px/1.6 var(--font-sans);color:var(--ink-muted)">Submit while empty to see the field block it.</output> </form>

// setup(root): properties and events setup(root) { const form = root.querySelector('#if-form'); const out = root.querySelector('#if-out'); form.addEventListener('submit', (e) => { e.preventDefault(); out.textContent = [...new FormData(form)].map(([k, v]) => `${k}=${v || '(empty)'}`).join(' '); }); }

Labeled, for a form

Set label, help or error and the field draws the same shell the rest of the InputText family draws, so an invalid field has somewhere to say why. Set none of them and nothing is added, which is the toolbar shape above.

Events

suiInput fires on every keystroke and suiChange on commit at blur or Enter. The X emits suiClear, then suiChange with an empty string, and puts focus back in the field. suiFocus and suiBlur follow the input, so a launcher can arm on focus without listening for the native focusin.

Idle.

// setup(root): properties and events setup(root) { const log = root.querySelector('#if-log'); const el = root.querySelector('#if-events'); el.addEventListener('suiFocus', () => { log.textContent = 'suiFocus'; }); el.addEventListener('suiBlur', () => { log.textContent = 'suiBlur'; }); el.addEventListener('suiInput', (e) => { log.textContent = `suiInput ${e.detail || '(empty)'}`; }); el.addEventListener('suiChange', (e) => { log.textContent = `suiChange ${e.detail || '(empty)'}`; }); el.addEventListener('suiClear', () => { log.textContent = 'suiClear'; }); }

Keyboard

Key	Action
`Tab`	Moves to the field, then to the clear control when there is text, then on.
`Printable characters`	Type into the native input; suiInput fires on every keystroke.
`Space` `Enter`	On the clear control, empties the field and returns focus to it.

API

`<sui-icon-field>`

Properties

Property	Attribute	Type	Default	Description
`autocomplete`	`autocomplete`	`string`string \| undefined		Native autocomplete hint, as on the five other elements that wrap a native text input. `inputmode` and `enterkeyhint` set on the host reach the input the same way, and `spellcheck` and `autocapitalize` on the host apply to it as they do to any descendant.
`clearable`	`clearable`	`boolean`	`false`	Shows an X that empties the field when it has a value: the search pattern. A clear emits `suiClear`, then `suiChange` with an empty string, and returns focus to the field.
`disabled`	`disabled`	`boolean`	`false`	Disables the field.
`endIcon`	`end-icon`	`string`string \| undefined		Icon at the end of the field, after the text, e.g. "fa-solid fa-chevron-down". It follows the reading direction, so it sits on the left under `dir="rtl"`. `icon` is the one at the start.
`error`	`error`	`string`string \| undefined		Error message under the field. Setting it paints the danger state and fails form validation.
`help`	`help`	`string`string \| undefined		Help text under the field.
`icon`	`icon`	`string`string \| undefined		Leading icon, before the text, e.g. "fa-solid fa-magnifying-glass".
`invalid`	`invalid`	`boolean`	`false`	Danger border.
`label`	`label`	`string`string \| undefined		Label above the field. Leave it unset for the bare toolbar shape, which is this element's default and what it was built for: with no `label`, `help` or `error` the shell draws nothing at all and the field is the same box it has always been, measured rather than assumed; the host's `aria-label` or `aria-labelledby` names the input then, or the placeholder. Set one of the three and it draws the shell the other five elements in the InputText family draw, which is what this element was missing: it carried `required` and `invalid` with nowhere to say why. A visible label wins over both host attributes.
`minLength`	`minlength`	`number`number \| undefined		Native `minlength`: a value shorter than this, once the user has typed, fails as `tooShort`.
`name`	`name`	`string`string \| undefined		Form control name. Reflected: form entry construction reads the content attribute, while all three framework bindings set properties, so an unreflected name posts nothing at all.
`pattern`	`pattern`	`string`string \| undefined		Native `pattern`: a regular expression the whole value must match. The browser checks it and the field reports `patternMismatch` on its validity, the way `required` reports `valueMissing`.
`placeholder`	`placeholder`	`string`string \| undefined		Placeholder text.
`readOnly`	`readonly`	`boolean`	`false`	Display only: the text can be selected and copied but not edited; the field still posts its value.
`required`	`required`	`boolean`	`false`	Marks the field required (valueMissing validity when empty). With no `label` set the browser's own bubble carries the message, named from the `aria-label` or the placeholder.
`size`	`size`	`"lg" \| "md" \| "sm"`	`'md'`	Control height: sm 28 for table rows, md 34 for forms and toolbars (the default, as on every other text field, the select family and the buttons, so a form built from defaults is one height), lg 42 for a sign-in or marketing page.
`type`	`type`	`SuiInputType`"email" \| "password" \| "search" \| "tel" \| "text" \| "url"	`'text'`	Native input type. One union across the four elements that wrap a native text input.
`value`	`value`	`string`	`''`	Current value. Mutable; listen to suiInput / suiChange to observe edits.
`width`	`width`	`number \| string \| undefined`		Field width as a CSS length or a pixel number. Defaults to 100%.

Events

Event	Detail	React	Vue	Description
`suiBlur`	`void`	`onSuiBlur`	`@sui-blur`	Fires when the input loses focus, to the clear control and the end slot included. Does not bubble.
`suiChange`	`string`	`onSuiChange`	`@sui-change`	Fires on commit (blur or Enter, native change) and after a clear; detail is the value.
`suiClear`	`void`	`onSuiClear`	`@sui-clear`	Fires when the clear control empties the field.
`suiFocus`	`void`	`onSuiFocus`	`@sui-focus`	Fires when the input takes focus, so a host can arm a launcher or a shortcut hint without listening for the native `focusin` on the element. Does not bubble.
`suiInput`	`string`	`onSuiInput`	`@sui-input`	Fires on every keystroke; detail is the current value.

Methods

Method	Signature	Description
`select()`	`select() => Promise<void>`	Selects the field text.
`setFocus()`	`setFocus() => Promise<void>`	Moves keyboard focus into the field.

Slots

Slot	Description
`end`	Trailing content inside the field's edge: a shortcut hint, a unit, a small action. It sits after the clear control and the trailing icon, centred on the field's height, and the input gives up room for it only while it is filled. A press on it that lands on nothing focusable puts the caret in the input, so a `sui-kbd` hint reads and behaves as part of the field.

Types

`SuiInputType` typeThe native `type` values the text-input skin draws. One union for the whole family: the four elements that wrap a native text input each listed a different subset in prose, which read as a rule and was not one. Anything outside this set has its own element (`sui-input-number`, `sui-date-picker`, `sui-color-picker`) or its own skin.
No members.

Theming

Every design token this element can render with, read from its own stylesheets and the ones it imports. Set a token on :root or on any ancestor and every use below follows it. The values shown are the ones in the theme you are viewing. The list is read per stylesheet, so an element that imports a shared drawing module lists that module's tokens too, whether or not it paints with all of them.

IconField

About

Usage

Basic

Sizes

Clearable and states

A hint in the end slot

In a form

Labeled, for a form

Events

Keyboard

API

`<sui-icon-field>`

Properties

Events

Methods

Slots

Types

Theming

Color12

Typography1

Spacing and size4

Radius2

Motion2

See also