Text field

Skip to page content

BETA

Component demo

Interactive example

What is your favourite coffee?

Such as Arabica, Robusta or Liberica

Web component

React

<ic-text-field
label="What is your favourite coffee?"
placeholder="Please enter…"
helper-text="Such as Arabica, Robusta or Liberica"
></ic-text-field>

<IcTextField
label="What is your favourite coffee?"
placeholder="Please enter…"
helperText="Such as Arabica, Robusta or Liberica"
onIcChange={(ev)=>console.log(ev.detail.value)}
/>

Text field details

Props

All components also accept native properties supported by the DOM, such asclassName and style .

Name	Description	Default
Property label Attribute label	The label for the input. Required type: string
Property autoFocus Attribute auto-focus	If`true` , the form control will have input focus when the page loads. type: boolean	false
Property autocapitalize Attribute autocapitalize	The automatic capitalisation of the text value as it is entered/edited by the user. Available options: "off", "none", "on", "sentences", "words", "characters". type: string	"off"
Property autocomplete Attribute autocomplete	The state of autocompletion the browser can apply on the text value. type: IcAutocompleteTypes - "name" \| "on" \| "off" \| "honorific-prefix" \| "given-name" \| "additional-name" \| "family-name" \| "honorific-suffix" \| "nickname" \| "email" \| "username" \| "new-password" \| "current-password" \| "one-time-code" \| "organization-title" \| "organization" \| "street-address" \| "address-line1" \| "address-line2" \| "address-line3" \| "address-level4" \| "address-level3" \| "address-level2" \| "address-level1" \| "country" \| "country-name" \| "postal-code" \| "cc-name" \| "cc-given-name" \| "cc-additional-name" \| "cc-family-name" \| "cc-number" \| "cc-exp" \| "cc-exp-month" \| "cc-exp-year" \| "cc-csc" \| "cc-type" \| "transaction-currency" \| "transaction-amount" \| "language" \| "bday" \| "bday-day" \| "bday-month" \| "bday-year" \| "sex" \| "tel" \| "tel-country-code" \| "tel-national" \| "tel-area-code" \| "tel-local" \| "tel-extension" \| "impp" \| "url" \| "photo"	"off"
Property autocorrect Attribute autocorrect	The state of autocorrection the browser can apply when the user is entering/editing the text value. type: IcAutocorrectStates - "off" \| "on"	"off"
Property debounce Attribute debounce	The amount of time, in milliseconds, to wait to trigger the`icChange` event after each keystroke. type: number	0
Property disabled Attribute disabled	If`true` , the disabled state will be set. type: boolean	false
Property fullWidth Attribute full-width	Specify whether the text field fills the full width of the container. If`true` , this overrides the --input-width CSS variable. type: boolean	false
Property helperText Attribute helper-text	The helper text that will be displayed for additional field guidance. type: string	""
Property hideLabel Attribute hide-label	If`true` , the label will be hidden and the required label value will be applied as an aria-label. type: boolean	false
Property inputId Attribute input-id	The ID for the input. type: string	`ic-text-field-input-${inputIds++}`
Property inputmode Attribute inputmode	A hint to the browser for which keyboard to display. Possible values:`"none"` ,`"text"` ,`"tel"` ,`"url"` ,`"email"` ,`"numeric"` ,`"decimal"` , and`"search"` . type: IcTextFieldInputModes - "decimal" \| "email" \| "none" \| "numeric" \| "search" \| "tel" \| "text" \| "url"	"text"
Property max Attribute max	The maximum number that can be accepted as a value, when`type` is`number` and`rows` is`1` . (NOTE: Ensure to include visual indication of max value in`helperText` or`label` ) type: string \| number - number \| string	undefined
Property maxCharacters Attribute max-characters	The maximum number of characters that can be entered in the field. Will display an error if too many characters are entered. type: number	0
Property maxLength Attribute max-length	The count of characters in the field. Will display a warning if the bound is reached. type: number	0
Property maxLengthMessage Attribute max-length-message	The text to display as the validation message when the maximum length is exceeded. type: string	"Maximum length exceeded"
Property min Attribute min	The minimum number that can be accepted as a value, when`type` is`number` and`rows` is`1` . (NOTE: Ensure to include visual indication of min value in`helperText` or`label` ) type: string \| number - number \| string	undefined
Property minCharacters Attribute min-characters	The minimum number of characters that can be entered in the field. type: number	0
Property name Attribute name	The name of the control, which is submitted with the form data. type: string	this.inputId
Property placeholder Attribute placeholder	The placeholder value to be displayed. type: string	""
Property readonly Attribute readonly	If`true` , the read only state will be set. type: boolean	false
Property required Attribute required	If`true` , the input will require a value. type: boolean	false
Property resize Attribute resize	If`true` , the multiline text area will be resizeable. type: boolean	false
Property rows Attribute rows	The number of rows to transform the text field into a text area with a specific height. type: number	1
Property size Attribute size	The size of the text field component. type: IcSizesNoLarge - "default" \| "small"	"default"
Property small Attribute small	This prop should not be used anymore. Set prop `size` to "small" instead. Deprecated	false
Property spellcheck Attribute spellcheck	If`true` , the value of the text field will have its spelling and grammar checked. type: boolean	false
Property type Attribute type	The type of control to display. The default type is text. type: IcTextFieldTypes - "email" \| "number" \| "password" \| "search" \| "tel" \| "text" \| "url"	"text"
Property validationInline Attribute validation-inline	If`true` , the icon in input control will be displayed - only applies when validationStatus ='success'. type: boolean	false
Property validationStatus Attribute validation-status	The validation state - e.g. 'error' \| 'warning' \| 'success'. type: IcInformationStatusOrEmpty - "" \| "error" \| "success" \| "warning"	""
Property validationText Attribute validation-text	The validation state - e.g. 'error' \| 'warning' \| 'success'. type: string	""
Property value Attribute value	The value of the text field. type: string	""

Property

label

Attribute

label

The label for the input.

Required

type: string

Property

autoFocus

Attribute

auto-focus

Iftrue , the form control will have input focus when the page loads.

type: boolean

Default: false

Property

autocapitalize

Attribute

autocapitalize

The automatic capitalisation of the text value as it is entered/edited by the user. Available options: "off", "none", "on", "sentences", "words", "characters".

type: string

Default: "off"

Property

autocomplete

Attribute

autocomplete

The state of autocompletion the browser can apply on the text value.

Default: "off"

Property

autocorrect

Attribute

autocorrect

The state of autocorrection the browser can apply when the user is entering/editing the text value.

type: IcAutocorrectStates - "off" | "on"

Default: "off"

Property

debounce

Attribute

debounce

The amount of time, in milliseconds, to wait to trigger theicChange event after each keystroke.

type: number

Default: 0

Property

disabled

Attribute

disabled

Iftrue , the disabled state will be set.

type: boolean

Default: false

Property

fullWidth

Attribute

full-width

Specify whether the text field fills the full width of the container. Iftrue , this overrides the --input-width CSS variable.

type: boolean

Default: false

Property

helperText

Attribute

helper-text

The helper text that will be displayed for additional field guidance.

type: string

Default: ""

Property

hideLabel

Attribute

hide-label

Iftrue , the label will be hidden and the required label value will be applied as an aria-label.

type: boolean

Default: false

Property

inputId

Attribute

input-id

The ID for the input.

type: string

Default: `ic-text-field-input-${inputIds++}`

Property

inputmode

Attribute

inputmode

A hint to the browser for which keyboard to display. Possible values:"none" ,"text" ,"tel" ,"url" ,"email" ,"numeric" ,"decimal" , and"search" .

Default: "text"

Property

max

Attribute

max

The maximum number that can be accepted as a value, whentype isnumber androws is1 . (NOTE: Ensure to include visual indication of max value inhelperText orlabel )

type: string | number - number | string

Default: undefined

Property

maxCharacters

Attribute

max-characters

The maximum number of characters that can be entered in the field. Will display an error if too many characters are entered.

type: number

Default: 0

Property

maxLength

Attribute

max-length

The count of characters in the field. Will display a warning if the bound is reached.

type: number

Default: 0

Property

maxLengthMessage

Attribute

max-length-message

The text to display as the validation message when the maximum length is exceeded.

type: string

Default: "Maximum length exceeded"

Property

min

Attribute

min

The minimum number that can be accepted as a value, whentype isnumber androws is1 . (NOTE: Ensure to include visual indication of min value inhelperText orlabel )

type: string | number - number | string

Default: undefined

Property

minCharacters

Attribute

min-characters

The minimum number of characters that can be entered in the field.

type: number

Default: 0

Property

name

Attribute

name

The name of the control, which is submitted with the form data.

type: string

Default: this.inputId

Property

placeholder

Attribute

placeholder

The placeholder value to be displayed.

type: string

Default: ""

Property

readonly

Attribute

readonly

Iftrue , the read only state will be set.

type: boolean

Default: false

Property

required

Attribute

required

Iftrue , the input will require a value.

type: boolean

Default: false

Property

resize

Attribute

resize

Iftrue , the multiline text area will be resizeable.

type: boolean

Default: false

Property

rows

Attribute

rows

The number of rows to transform the text field into a text area with a specific height.

type: number

Default: 1

Property

size

Attribute

size

The size of the text field component.

type: IcSizesNoLarge - "default" | "small"

Default: "default"

Property

small

Attribute

small

This prop should not be used anymore. Set prop `size` to "small" instead.

Deprecated

Default: false

Property

spellcheck

Attribute

spellcheck

Iftrue , the value of the text field will have its spelling and grammar checked.

type: boolean

Default: false

Property

type

Attribute

type

The type of control to display. The default type is text.

Default: "text"

Property

validationInline

Attribute

validation-inline

Iftrue , the icon in input control will be displayed - only applies when validationStatus ='success'.

type: boolean

Default: false

Property

validationStatus

Attribute

validation-status

The validation state - e.g. 'error' | 'warning' | 'success'.

type: IcInformationStatusOrEmpty - "" | "error" | "success" | "warning"

Default: ""

Property

validationText

Attribute

validation-text

The validation state - e.g. 'error' | 'warning' | 'success'.

type: string

Default: ""

Property

value

Attribute

value

The value of the text field.

type: string

Default: ""

Slots

A slot allows for any type of element or markup to be passed into and rendered within a web component. This creates more flexibility than using a prop which must take a specific type of data.

Content can be slotted into a component by adding it as a top-level child of the component.

Slots can have a name to identify them. These specify which slot the content will be inserted into, and therefore where it will be rendered and how it will be used within the component. The name of the slot to be used can be specified by passing it via a slot attribute on the slotted content.

Name	Description
Slot icon	Content will be placed to the left of the text input.

CSS Custom Properties

Name	Description
--input-width	Width of the input field

--input-width Width of the input field

Events

All components also accept native events supported by the DOM, such as onClick and onKeyDown .

Name	Description	Signature
Web component icBlur React onIcBlur	Emitted when input loses focus.	IcValueEventDetail
Web component icChange React onIcChange	Emitted when the value has changed.	IcValueEventDetail
Web component icFocus React onIcFocus	Emitted when input gains focus.	IcValueEventDetail
Web component icInput React onIcInput	Emitted when a keyboard input occurred.	IcValueEventDetail
Web component icKeydown React onIcKeydown	Emitted when a keydown event occurred.	{ event: KeyboardEvent; }

Web component

icBlur

React

onIcBlur

Emitted when input loses focus.

IcValueEventDetail

Web component

icChange

React

onIcChange

Emitted when the value has changed.

IcValueEventDetail

Web component

icFocus

React

onIcFocus

Emitted when input gains focus.

IcValueEventDetail

Web component

icInput

React

onIcInput

Emitted when a keyboard input occurred.

IcValueEventDetail

Web component

icKeydown

React

onIcKeydown

Emitted when a keydown event occurred.

{ event: KeyboardEvent; }

Methods

Name	Description	Signature
Method setFocus	Sets focus on the native `input`.	setFocus() => Promise<void>

Method

setFocus

Sets focus on the native `input`.

setFocus() => Promise<void>

Variants

With icon, value and max length

Interactive example

What is your favourite coffee? *

Such as Arabica, Robusta or Liberica

7/25 Field can contain a maximum of 25 characters.

Web component

React

<ic-text-field
max-length="25"
value="Arabica"
label="What is your favourite coffee?"
required="true"
placeholder="Please enter…"
helper-text="Such as Arabica, Robusta or Liberica"
>
<svg
slot="icon"
xmlns="http://www.w3.org/2000/svg"
width="24"
height="24"
viewBox="0 0 24 24"
fill="#000000"
>
<pathd="M2,21H20V19H2M20,8H18V5H20M20,3H4V13A4,4 0 0,0 8,17H14A4,4 0 0,0 18,13V10H20A2,2 0 0,0 22,8V5C22,3.89 21.1,3 20,3Z"/>
</svg>
</ic-text-field>

<IcTextField
maxLength={25}
value="Arabica"
label="What is your favourite coffee?"
required
placeholder="Please enter…"
helperText="Such as Arabica, Robusta or Liberica"
>
<SlottedSVG
slot="icon"
xmlns="http://www.w3.org/2000/svg"
width="24"
height="24"
viewBox="0 0 24 24"
fill="#000000"
>
<pathd="M2,21H20V19H2M20,8H18V5H20M20,3H4V13A4,4 0 0,0 8,17H14A4,4 0 0,0 18,13V10H20A2,2 0 0,0 22,8V5C22,3.89 21.1,3 20,3Z"/>
</SlottedSVG>
</IcTextField>

Disabled

Interactive example

What is your favourite coffee? *

Web component

React

<ic-text-field
label="What is your favourite coffee?"
required="true"
placeholder="Please enter…"
disabled="true"
>
<svg
slot="icon"
xmlns="http://www.w3.org/2000/svg"
width="24"
height="24"
viewBox="0 0 24 24"
fill="#000000"
>
<pathd="M0 0h24v24H0z"fill="none"/>
<pathd="M17 3H7c-1.1 0-1.99.9-1.99 2L5 21l7-3 7 3V5c0-1.1-.9-2-2-2z"/>
</svg>
</ic-text-field>

<IcTextField
label="What is your favourite coffee?"
required
placeholder="Please enter…"
disabled
>
<SlottedSVG
slot="icon"
xmlns="http://www.w3.org/2000/svg"
width="24"
height="24"
viewBox="0 0 24 24"
fill="#000000"
>
<pathd="M0 0h24v24H0z"fill="none"/>
<pathd="M17 3H7c-1.1 0-1.99.9-1.99 2L5 21l7-3 7 3V5c0-1.1-.9-2-2-2z"/>
</SlottedSVG>
</IcTextField>

Size small

Interactive example

What is your favourite coffee?

Web component

React

<ic-text-field
label="What is your favourite coffee?"
placeholder="Please enter…"
size="small"
></ic-text-field>

<IcTextField
label="What is your favourite coffee?"
placeholder="Please enter…"
size="small"
onIcChange={(ev)=>console.log(ev.detail.value)}
/>

Validation

Interactive example

What is your favourite coffee? *

Such as Arabica, Robusta or Liberica

Good choice!

7/25 Field can contain a maximum of 25 characters.

What is your favourite coffee? *

Such as Arabica, Robusta or Liberica

7/25 Field can contain a maximum of 25 characters.

What is your favourite coffee? *

Such as Arabica, Robusta or Liberica

There’s only a few left! Order now to avoid missing out.

7/25 Field can contain a maximum of 25 characters.

What is your favourite coffee? *

Such as Arabica, Robusta or Liberica

Now it has really gone to (coffee) pot

3/25 Field can contain a maximum of 25 characters.

Web component

React

<ic-text-field
validation-status="success"
validation-text="Good choice!"
value="Arabica"max-length="25"
label="What is your favourite coffee?"
required="true"placeholder="Please enter…"
helper-text="Such as Arabica, Robusta or Liberica"
></ic-text-field>
<ic-text-field
validation-status="success"
validation-text="Good choice!"
validation-inline="true"
value="Arabica"
max-length="25"
label="What is your favourite coffee?"
required="true"placeholder="Please enter…"
helper-text="Such as Arabica, Robusta or Liberica"
></ic-text-field>
<ic-text-field
validation-status="warning"
validation-text="There’s only a few left! Order now to avoid missing out."
value="Arabica"
max-length="25"
label="What is your favourite coffee?"
required="true"
placeholder="Please enter…"
helper-text="Such as Arabica, Robusta or Liberica"
></ic-text-field>
<ic-text-field
validation-status="error"
validation-text="now it has really gone to (coffee) pot"
value="Tea"
max-length="25"
label="What is your favourite coffee?"
required="true"
placeholder="Please enter…"
helper-text="Such as Arabica, Robusta or Liberica"
></ic-text-field>

<IcTextField
maxLength={25}
value="Arabica"
label="What is your favourite coffee?"
required
placeholder="Please enter…"
helperText="Such as Arabica, Robusta or Liberica"
validationStatus="success"
validationText="Good choice!"
/>
<IcTextField
maxLength={25}
value="Arabica"
label="What is your favourite coffee?"
required
placeholder="Please enter…"
helperText="Such as Arabica, Robusta or Liberica"
validationStatus="success"
validationText="Good choice!"
validationInline
/>
<IcTextField
maxLength={25}
value="Arabica"
label="What is your favourite coffee?"
required
placeholder="Please enter…"
helperText="Such as Arabica, Robusta or Liberica"
validationStatus="warning"
validationText="There’s only a few left! Order now to avoid missing out."
/>
<IcTextField
maxLength={25}
value="Tea"
label="What is your favourite coffee?"
required
placeholder="Please enter…"
helperText="Such as Arabica, Robusta or Liberica"
validationStatus="error"
validationText="Now it has really gone to (coffee) pot"
/>

With min and max values

In this example, an error message will display when the input is either below the min value or above the max value. This only affects numeric input fields.

Interactive example

How many coffees do you want?

Our coffee machines have a maximum capacity of 4 coffees at a time.

Maximum value of 4 exceeded

Web component

React

<ic-text-field
label="How many coffees do you want?"
helper-text="Our coffee machines have a maximum capacity of 4 coffees at a time."
placeholder="Please enter…"
type="number"
inputmode="numeric"
min="1"
max="4"
value="6"
></ic-text-field>

<IcTextField
label="How many coffees do you want?"
helperText="Our coffee machines have a maximum capacity of 4 coffees at a time."
placeholder="Please enter…"
type="number"
inputmode="numeric"
min={1}
max={4}
value="6"
/>

Text area with resize

Interactive example

What is your favourite coffee?

Such as Arabica, Robusta or Liberica

Web component

React

<ic-text-field
rows="6"
resize="true"
label="What is your favourite coffee?"
placeholder="Please enter…"
helper-text="Such as Arabica, Robusta or Liberica"
></ic-text-field>

<IcTextField
rows={6}
resize
label="What is your favourite coffee?"
placeholder="Please enter…"
helperText="Such as Arabica, Robusta or Liberica"
/>

Last reviewed 31 May 2024 .