@dotconnor/grommet
Version:
focus on the essential experience
525 lines (357 loc) • 7.69 kB
Markdown
## TextInput
A control to input a single line of text, with optional suggestions.
[](https://storybook.grommet.io/?selectedKind=Input-TextInput&full=0&stories=1&panelRight=0) [](https://codesandbox.io/s/github/grommet/grommet-sandbox?initialpath=/textinput&module=%2Fsrc%2FTextInput.js)
## Usage
```javascript
import { TextInput } from 'grommet';
<TextInput id='item' name='item' />
```
## Properties
**a11yTitle**
Custom title to be used by screen readers.
```
string
```
**dropAlign**
How to align the drop. Defaults to `{
"top": "bottom",
"left": "left"
}`.
```
{
top:
top
bottom,
bottom:
top
bottom,
right:
left
right,
left:
left
right
}
```
**dropHeight**
The height of the drop container.
```
xsmall
small
medium
large
xlarge
string
```
**dropTarget**
Target where any suggestions drop will be aligned to. This should be
a React reference. Typically, this is not required as the drop will be
aligned to the TextInput itself by default.
```
object
```
**dropProps**
Any valid Drop prop.
```
object
```
**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
```
**id**
The id attribute of the input.
```
string
```
**focusIndicator**
Whether the plain text input should receive a focus outline.
```
boolean
```
**messages**
Custom messages for TextInput. Used for accessibility by screen
readers. Defaults to `{
"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"
}`.
```
{
enterSelect: string,
suggestionsCount: string,
suggestionsExist: string,
suggestionIsOpen: string
}
```
**name**
The name of the attribute when in a Form or FormField.
```
string
```
**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
```
**onSuggestionsOpen**
Function that will be called when the suggestions drop is opened.
```
function
```
**onSuggestionsClose**
Function that will be called when the suggestions drop is closed.
```
function
```
**placeholder**
Placeholder to use when no value is provided.
```
node
```
**plain**
Whether this is a plain input with no border or outline.
Use "full" to remove padding in addition to removing border and outline.
Only use this when the containing context provides sufficient
affordance.
```
boolean
full
```
**reverse**
Whether an icon should be reversed so that the icon is at the
end of the input.
```
boolean
```
**size**
The size of the TextInput.
```
small
medium
large
xlarge
string
```
**suggestions**
Suggestions to show. It is recommended to avoid showing too many
suggestions and instead rely on the user to type more.
```
[
{
label: node,
value: any
}
string
]
```
**textAlign**
How to align the text inside the input. Defaults to `start`.
```
start
center
end
```
**value**
What text to put in the input.
```
string
number
```
## Intrinsic element
```
input
```
## Theme
**global.colors.border**
The color of the border. Expects `object`.
Defaults to
```
[object Object]
```
**global.control.border.color**
The border color. Expects `string`.
Defaults to
```
border
```
**global.control.border.radius**
The border radius. Expects `string`.
Defaults to
```
4px
```
**global.control.border.width**
The border width. Expects `string`.
Defaults to
```
1px
```
**select.step**
How many suggestions to render at a time. Expects `number`.
Defaults to
```
20
```
**text**
The possible sizes of the text in terms of its font-size and
line-height. Expects `object`.
Defaults to
```
{
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. Expects `string | (props) => {}`.
Defaults to
```
undefined
```
**textInput.container.extend**
Any additional style for TextInput container. Expects `string | (props) => {}`.
Defaults to
```
undefined
```
**textInput.placeholder.extend**
Any additional style for non-string placeholder inside TextInput. Expects `string | (props) => {}`.
Defaults to
```
undefined
```
**textInput.suggestions.extend**
Any additional style for TextInput suggestions. Expects `string | (props) => {}`.
Defaults to
```
undefined
```
**textInput.disabled.opacity**
The opacity when the textInput is disabled. Expects `number | string`.
Defaults to
```
undefined
```
**global.focus.border.color**
The border color of the component when in focus. Expects `string | { dark: string, light: string }`.
Defaults to
```
focus
```
**global.focus.outline.color**
The outline color around the component when in focus. Expects `string | { dark: string, light: string }`.
Defaults to
```
undefined
```
**global.focus.outline.size**
The size of the outline around the component when in focus. Expects `string`.
Defaults to
```
undefined
```
**global.focus.shadow.color**
The shadow color around the component when in focus. Expects `string | { dark: string, light: string }`.
Defaults to
```
focus
```
**global.focus.shadow.size**
The size of the shadow around the component when in focus. Expects `string`.
Defaults to
```
2px
```
**global.colors.placeholder**
The placeholder color used for the component. Expects `string`.
Defaults to
```
#AAAAAA
```
**global.control.disabled.opacity**
The opacity when a component is disabled. Expects `number`.
Defaults to
```
0.3
```
**global.input.font.height**
The line-height of the text. Expects `string`.
Defaults to
```
undefined
```
**global.input.font.size**
The size of the text. Expects `string`.
Defaults to
```
undefined
```
**global.input.font.weight**
The font-weight of the text. This value will only be
applied if global.input.weight is undefined. Expects `number | string`.
Defaults to
```
600
```
**global.input.weight**
This value has been deprecated and replaced by
global.input.font.weight. Expects `number | string`.
Defaults to
```
undefined
```
**global.input.padding**
The padding of the text. Expects `string | { top: string, bottom: string, left: string, right:
string, horizontal: string, vertical: string }`.
Defaults to
```
12px
```
**global.input.extend**
Any additional style for an input. Expects `string | (props) => {}`.
Defaults to
```
undefined
```