grommet
components

TextInput

a control to input a single line of text, with optional suggestions

Storybook
CodeSandbox

Props

a11yTitle

Custom title to be used by screen readers.

string
"a user friendly label for screen readers"

defaultSuggestion

Default suggestion to highlight, as an index into the suggestions array.

number

If set, the suggestion at the specified index in the suggestions array will be highlighted by default when the suggestions drop opens.

0

dropAlign

How to align the drop.

object

{
  top: "top" | "bottom",
  bottom: "top" | "bottom",
  right: "left" | "right",
  left: "left" | "right"
}
            
{ top: "bottom", left: "left" }

dropHeight

The height of the drop container.

string
"xsmall"
"small"
"medium"
"large"
"xlarge"
"string"

dropProps

Any valid Drop prop.

object
{}

dropTarget

Target where any suggestions drop will be aligned to.

object

This should be a React reference. Typically, this is not required as the drop will be aligned to the TextInput itself by default.

ref.current

focusIndicator

Whether the plain TextInput should receive a focus outline.

boolean
true
false

icon

An optional icon to show. This could be used to provide an indication of what kind of input is expected, like an email icon, or what the input will be used for, like a search icon.

element
<Search />

id

The id attribute of the input.

string
"id"

messages

Custom messages for TextInput. Used for accessibility by screen readers.

object
{
  enterSelect: "(Press Enter to Select)", 
  suggestionsCount: "suggestions available", 
  suggestionsExist: "This input has suggestions use arrow keys to navigate", 
  suggestionIsOpen: "Suggestions drop is open, continue to use arrow keys to navigate"
}

name

The name of the attribute when in a Form or FormField.

string
"name"

onChange

Function that will be called when the user types in the input.

function
() => {}

onSelect

Note: This function is deprecated, use onSuggestionSelect instead. Function that will be called when the user selects a suggestion. The suggestion contains the object chosen from the supplied suggestions. When used in conjunction with onSuggestionSelect this will default to React's onSelect.

function
() => {}

onSuggestionSelect

Function that will be called when the user selects a suggestion. The suggestion contains the object chosen from the supplied suggestions.

function
() => {}

onSuggestionsClose

Function that will be called when the suggestions drop is closed.

function
() => {}

onSuggestionsOpen

Function that will be called when the suggestions drop is opened.

function
() => {}

placeholder

Placeholder to use when no value is provided.

node
"placeholder"
<Box>...</Box>

plain

Whether this is a plain input with no border or outline.

boolean
true
false
string

Use "full" to remove padding in addition to removing border and outline. Only use this when the containing context provides sufficient affordance.

"full"

reverse

Whether an icon should be reversed so that the icon is at the end of the input.

boolean
true
false

size

The size of the text.

string
"xsmall"
"small"
"medium"
"large"
"xlarge"
"xxlarge"
"2xl"
"3xl"
"4xl"
"5xl"
"6xl"
"string"

suggestions

Suggestions to show. It is recommended to avoid showing too many suggestions and instead rely on the user to type more.

array[string]
["suggestion1", "suggestion2"]
array[object]

[
  {
    label: node,
    value: any
  },
]

textAlign

How to align the text inside the input.

string
"start"
"center"
"end"

value

What text to put in the input.

string
"text"
number
0

React/DOM Properties

At its core, the TextInput component is a regular <input> element. Thus, both DOM and React properties, methods, and events are accessible. To read up on all of the possible DOM attributes and types available for input elements, check out this MDN Web Documents page. To learn more about DOM events and methods, you can read more on the MDN Web Events documentation page.

Also, feel free to read about the types of React events available, or see how DOM attributes change in React. Working in tandem with Styled Components, you also have access to the as property.

Theme

global.colors.border

The color of the border.

string

A hex, name, or rgb value.

"rgba(0, 0, 0, 0.33)"
object

An object with a color for dark and light modes.

{ dark: "rgba(255, 255, 255, 0.33)", light: "rgba(0, 0, 0, 0.33)" }

global.control.border.color

The border color.

string
"border"

global.control.border.radius

The border radius.

string
"4px"

global.control.border.width

The border width.

string
"1px"

select.step

How many suggestions to render at a time.

number
 20

text

The possible sizes of the text in terms of its font-size and line-height.

object
{
  xsmall: {
    size: '12px',
    height: '18px',
  },
  small: {
    size: '14px',
    height: '20px',
  },
  medium: {
    size: '18px',
    height: '24px',
  },
  large: {
    size: '22px',
    height: '28px',
  },
  xlarge: {
    size: '26px',
    height: '32px',
  },
  xxlarge: {
    size: '34px',
    height: '40px',
  },
}

textInput.extend

Any additional style for TextInput.

string

Any CSS.

css`color: 'blue'`
function
(props) => {}

textInput.container.extend

Any additional style for TextInput container.

string

Any CSS.

css`color: 'blue'`
function
(props) => {}

textInput.placeholder.extend

Any additional style for non-string placeholder inside TextInput.

string

Any CSS.

css`color: 'blue'`
function
(props) => {}

textInput.suggestions.extend

Any additional style for TextInput suggestions.

string

Any CSS.

css`color: 'blue'`
function
(props) => {}

textInput.disabled.opacity

The opacity when the textInput is disabled.

string
"medium"
number
0.5

global.focus.border.color

The border color of the component when in focus.

string

A hex, name, or rgb value.

"focus"
object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

global.focus.outline.color

The outline color around the component when in focus.

string

A hex, name, or rgb value.

"brand"
object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

global.focus.outline.size

The size of the outline around the component when in focus.

string
"2px"

global.focus.shadow.color

The shadow color around the component when in focus.

string
"focus"
object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

global.focus.shadow.size

The size of the shadow around the component when in focus.

string
"2px"

global.colors.placeholder

The placeholder color used for the component.

string
"#AAAAAA"

global.control.disabled.opacity

The opacity when a component is disabled.

number
0.3

global.input.font.height

The line-height of the text.

string
"normal"

global.input.font.size

The size of the text.

string
"18px"

global.input.font.weight

The font-weight of the text. This value will only be applied if global.input.weight is undefined.

string
"bold"
number
600

global.input.weight

This value has been deprecated and replaced by global.input.font.weight.

string
"bold"
number
300

global.input.padding

The padding of the text.

string
"12px"
object

An object specifying padding for different sides of the component.


{ 
  top: "string", 
  bottom: "string", 
  left: "string", 
  right: "string", 
  horizontal: "string", 
  vertical: "string" 
}

global.input.extend

Any additional style for an input.

string

Any CSS.

css`color: 'blue'`
function
(props) => {}

Examples