View Source

TokenizedInput

Distill rich entity data matched via typeahead input into simple visual abstractions.

Basic usage of this component is identical to that of Typeahead. Additional props are available to take advantage of the tokenization functionality.

Installation#

npm i --save boundless-tokenized-input

TokenizedInput can also just be directly used from the main Boundless library. This is recommended when you're getting started to avoid maintaining the package versions of several components:

npm i boundless --save

the ES6 import statement then becomes like:

import { TokenizedInput } from 'boundless';

Demo

Enter a country you'd like to visit:

Aruba
Curaçao
Sweden
Show Implementation

Component Instance Methods#

When using TokenizedInput in your project, you may call the following methods on a rendered instance of the component. Use refs to get the instance.

  • add(index: number) programmatically creates a token for props.entities[index]; props.handleAddToken will be called as a hint to persist the change in * your controller view or other application state

  • focus() focuses the browser oon the underlying textual input for immediate text entry

  • getInputNode() returns the raw underlying textual input DOM node

  • getSelectedEntityText() returns the text property of the currently highlighted entity (from props.entities), or returns an empty string

  • getValue() retrieves the current value of the underlying textual input

  • remove(index: number) programmatically removes the token for props.entities[index]; props.handleRemoveTokens will be called as a hint to persist the * change in your controller view or other application state

  • select() programmatically creates a full selection on the underlying textual input such that a press of the Backspace key would fully clear the * input

  • setValue(value: string) sets the underlying textual input to the specified text and updates internal state; do not use this method when using Typeahead as a "controlled input"

Props#

Required Props#

There are no required props.

Optional Props#

NameImplementationDescription
*
Expects
any

any React-supported attribute

algorithm
Expects
Typeahead.mode.STARTS_WITH or
Typeahead.mode.FUZZY or object
Default Value
Typeahead.mode.FUZZY

the mechanism used to identify and mark matching substrings; a custom set can be provided as an object (see the properties below)

clearOnSelection
Expects
bool
Default Value
false

if true, clears the input text when a (partial) match is selected

component
Expects
string
Default Value
'div'

overrides the HTML container tag

entities
Expects
arrayOf(object)
Default Value
[]

an array of objects that user input is filtered against; at a minimum, each object must have a text property and any other supplied property is passed through to the resulting DOM element

text
Expects
string

the text to be used to do string comparison and match against

handleAddToken
Expects
function
Default Value
() => {}

function handler that is called when an entity is selected by the user and a token should be created

handleNewSelection
Expects
function
Default Value
() => {}

function handler that is called when one or more tokens are selected by the user via click or keyboard actions; called with what the new selection should be

handleRemoveTokens
Expects
function
Default Value
() => {}

function handler that is called when one or more tokens are removed by the user via clicking the "close" button or pressing the Backspace key while tokens are selected

hidePlaceholderOnFocus
Expects
bool
Default Value
true

triggers the placeholder to disappear when the input field is focused, reappears when the user has tabbed away or focus is moved

hint
Expects
bool
Default Value
null

renders a disabled textfield with the full text of the currently selected input hint; will remain blank if the matched substring is not at the beginning of the user input

hintProps
Expects
object
Default Value
{}
*
Expects
any

any React-supported attribute

inputProps
Expects
object
Default Value
{
    type: 'text',
}
*
Expects
any

any React-supported attribute

defaultValue
Expects
string
onBlur
Expects
function
onFocus
Expects
function
onChange
Expects
function
placeholder
Expects
string
type
Expects
string
value
Expects
string
matchWrapperProps
Expects
object
Default Value
{}
*
Expects
any

any React-supported attribute

offscreenClass
Expects
string
Default Value
'b-offscreen'

the "offscreen" class used by your application; specifically to retain ARIA navigability as display: none excludes the element from consideration

onComplete
Expects
function
Default Value
() => {}

called when the user presses Enter with no autosuggest hint available, indicating that input is complete

onEntityHighlighted
Expects
function
Default Value
() => {}

called with the index of the highlighted entity due to keyboard selection

onEntitySelected
Expects
function
Default Value
() => {}

called with the index of the entity selected by the user

tokenCloseComponent
Expects
ReactElement
Default Value
<div>X</div>

the JSX used for the close button itself

tokenCloseVisible
Expects
bool
Default Value
true

determines if the .b-tokenfield-token-close element should be rendered for each token

tokens
Expects
arrayOf(number)
Default Value
[]

the indexes of entities that should be rendered as "tokens" in the component UI

tokensSelected
Expects
arrayOf(number)
Default Value
[]

the indexes of tokenized entities that are part of an active selection; the user can press Backspace to trigger handleRemoveTokens