Natural Pacifist Manatees

    boundless-tokenized-input

    1.1.0 • Public • Published

    TokenizedInput

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

    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"

    Installation

    npm i boundless-tokenized-input --save

    Then use it like:

    /** @jsx createElement */
     
    import { without } from 'lodash';
    import { createElement, PureComponent } from 'react';
    import TokenizedInput from 'boundless-tokenized-input';
    import Typeahead from 'boundless-typeahead';
     
    const countries = [ 'Afghanistan', 'Albania', 'Algeria', 'American Samoa', 'Andorra', 'Angola', 'Anguilla', 'Antarctica', 'Antigua and Barbuda', 'Argentina', 'Armenia', 'Aruba', 'Australia', 'Austria', 'Azerbaijan', 'Bahamas', 'Bahrain', 'Bangladesh', 'Barbados', 'Belarus', 'Belgium', 'Belize', 'Benin', 'Bermuda', 'Bhutan', 'Bolivia', 'Bosnia and Herzegovina', 'Botswana', 'Bouvet Island', 'Brazil', 'British Indian Ocean Territory', 'Brunei Darussalam', 'Bulgaria', 'Burkina Faso', 'Burundi', 'Cambodia', 'Cameroon', 'Canada', 'Cape Verde', 'Caribbean Netherlands', 'Cayman Islands', 'Central African Republic', 'Chad', 'Chile', 'China', 'Christmas Island', 'Cocos (Keeling) Islands', 'Colombia', 'Comoros', 'Congo', 'Congo, Democratic Republic of', 'Cook Islands', 'Costa Rica', 'Croatia', 'Cuba', 'Curaçao', 'Cyprus', 'Czech Republic', 'Côte d\'Ivoire', 'Denmark', 'Djibouti', 'Dominica', 'Dominican Republic', 'Ecuador', 'Egypt', 'El Salvador', 'Equatorial Guinea', 'Eritrea', 'Estonia', 'Ethiopia', 'Falkland Islands', 'Faroe Islands', 'Fiji', 'Finland', 'France', 'French Guiana', 'French Polynesia', 'French Southern Territories', 'Gabon', 'Gambia', 'Georgia', 'Germany', 'Ghana', 'Gibraltar', 'Greece', 'Greenland', 'Grenada', 'Guadeloupe', 'Guam', 'Guatemala', 'Guernsey', 'Guinea', 'Guinea-Bissau', 'Guyana', 'Haiti', 'Heard and McDonald Islands', 'Honduras', 'Hong Kong', 'Hungary', 'Iceland', 'India', 'Indonesia', 'Iran', 'Iraq', 'Ireland', 'Isle of Man', 'Israel', 'Italy', 'Jamaica', 'Japan', 'Jersey', 'Jordan', 'Kazakhstan', 'Kenya', 'Kiribati', 'Kuwait', 'Kyrgyzstan', 'Lao People\'s Democratic Republic', 'Latvia', 'Lebanon', 'Lesotho', 'Liberia', 'Libya', 'Liechtenstein', 'Lithuania', 'Luxembourg', 'Macau', 'Macedonia', 'Madagascar', 'Malawi', 'Malaysia', 'Maldives', 'Mali', 'Malta', 'Marshall Islands', 'Martinique', 'Mauritania', 'Mauritius', 'Mayotte', 'Mexico', 'Micronesia, Federated States of', 'Moldova', 'Monaco', 'Mongolia', 'Montenegro', 'Montserrat', 'Morocco', 'Mozambique', 'Myanmar', 'Namibia', 'Nauru', 'Nepal', 'New Caledonia', 'New Zealand', 'Nicaragua', 'Niger', 'Nigeria', 'Niue', 'Norfolk Island', 'North Korea', 'Northern Mariana Islands', 'Norway', 'Oman', 'Pakistan', 'Palau', 'Palestine, State of', 'Panama', 'Papua New Guinea', 'Paraguay', 'Peru', 'Philippines', 'Pitcairn', 'Poland', 'Portugal', 'Puerto Rico', 'Qatar', 'Romania', 'Russian Federation', 'Rwanda', 'Réunion', 'Saint Barthélemy', 'Saint Helena', 'Saint Kitts and Nevis', 'Saint Lucia', 'Saint Vincent and the Grenadines', 'Saint-Martin (France)', 'Samoa', 'San Marino', 'Sao Tome and Principe', 'Saudi Arabia', 'Senegal', 'Serbia', 'Seychelles', 'Sierra Leone', 'Singapore', 'Sint Maarten (Dutch part)', 'Slovakia', 'Slovenia', 'Solomon Islands', 'Somalia', 'South Africa', 'South Georgia and the South Sandwich Islands', 'South Korea', 'South Sudan', 'Spain', 'Sri Lanka', 'St. Pierre and Miquelon', 'Sudan', 'Suriname', 'Svalbard and Jan Mayen Islands', 'Swaziland', 'Sweden', 'Switzerland', 'Syria', 'Taiwan', 'Tajikistan', 'Tanzania', 'Thailand', 'The Netherlands', 'Timor-Leste', 'Togo', 'Tokelau', 'Tonga', 'Trinidad and Tobago', 'Tunisia', 'Turkey', 'Turkmenistan', 'Turks and Caicos Islands', 'Tuvalu', 'Uganda', 'Ukraine', 'United Arab Emirates', 'United Kingdom', 'United States', 'United States Minor Outlying Islands', 'Uruguay', 'Uzbekistan', 'Vanuatu', 'Vatican', 'Venezuela', 'Vietnam', 'Virgin Islands (British)', 'Virgin Islands (U.S.)', 'Wallis and Futuna Islands', 'Western Sahara', 'Yemen', 'Zambia', 'Zimbabwe' ];
     
    export default class TokenizedInputDemo extends PureComponent {
        state = {
            countries: countries.map((name) => ({ text: name })),
            tokens: [ 11, 55, 211 ],
            tokensSelected: [],
        }
     
        addTokenByEntityIndex = (index) => {
            this.setState({ tokens: this.state.tokens.concat(index) });
        }
     
        removeTokensByEntityIndexes = (indexes) => {
            this.setState({
                tokens: without(this.state.tokens, ...indexes),
                tokensSelected: without(this.state.tokensSelected, ...indexes),
            });
        }
     
        handleSelectionByEntityIndexes = (indexes) => {
            this.setState({ tokensSelected: indexes });
        }
     
        render() {
            return (
                <div>
                    <p>Enter a country you'd like to visit:</p>
                    <TokenizedInput
                        algorithm={Typeahead.mode.FUZZY}
                        entities={this.state.countries}
                        handleAddToken={this.addTokenByEntityIndex}
                        handleRemoveTokens={this.removeTokensByEntityIndexes}
                        handleNewSelection={this.handleSelectionByEntityIndexes}
                        hint={true}
                        tokenCloseComponent={<span></span>}
                        tokens={this.state.tokens}
                        tokensSelected={this.state.tokensSelected} />
                </div>
            );
        }
    }

    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';

    Props

    Note: only top-level props are in the README, for the full list check out the website.

    Required Props

    There are no required props.

    Optional Props

    • * · any React-supported attribute

      Expects Default Value
      any n/a
    • algorithm · the mechanism used to identify and mark matching substrings; a custom set can be provided as an object (see the properties below)

      Expects Default Value
      Typeahead.mode.STARTS_WITH or Typeahead.mode.FUZZY or object Typeahead.mode.FUZZY
    • clearOnSelection · if true, clears the input text when a (partial) match is selected

      Expects Default Value
      bool false
    • component · overrides the HTML container tag

      Expects Default Value
      string 'div'
    • entities · 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

      Expects Default Value
      arrayOf(object) []
    • handleAddToken · function handler that is called when an entity is selected by the user and a token should be created

      Expects Default Value
      function () => {}
    • handleNewSelection · 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

      Expects Default Value
      function () => {}
    • handleRemoveTokens · 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

      Expects Default Value
      function () => {}
    • hidePlaceholderOnFocus · triggers the placeholder to disappear when the input field is focused, reappears when the user has tabbed away or focus is moved

      Expects Default Value
      bool true
    • hint · 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

      Expects Default Value
      bool null
    • hintProps

      Expects Default Value
      object {}
    • inputProps

      Expects Default Value
      object { type: 'text' }
    • matchWrapperProps

      Expects Default Value
      object {}
    • offscreenClass · the "offscreen" class used by your application; specifically to retain ARIA navigability as display: none excludes the element from consideration

      Expects Default Value
      string 'b-offscreen'
    • onComplete · called when the user presses Enter with no autosuggest hint available, indicating that input is complete

      Expects Default Value
      function () => {}
    • onEntityHighlighted · called with the index of the highlighted entity due to keyboard selection

      Expects Default Value
      function () => {}
    • onEntitySelected · called with the index of the entity selected by the user

      Expects Default Value
      function () => {}
    • tokenCloseComponent · the JSX used for the close button itself

      Expects Default Value
      ReactElement <div>X</div>
    • tokenCloseVisible · determines if the .b-tokenfield-token-close element should be rendered for each token

      Expects Default Value
      bool true
    • tokens · the indexes of entities that should be rendered as "tokens" in the component UI

      Expects Default Value
      arrayOf(number) []
    • tokensSelected · the indexes of tokenized entities that are part of an active selection; the user can press Backspace to trigger handleRemoveTokens

      Expects Default Value
      arrayOf(number) []

    Reference Styles

    Stylus

    You can see what variables are available to override in variables.styl.

    // Redefine any variables as desired, e.g:
    color-accent = royalblue
     
    // Bring in the component styles; they will be autoconfigured based on the above
    @require "node_modules/boundless-tokenized-input/style"

    CSS

    If desired, a precompiled plain CSS stylesheet is available for customization at /build/style.css, based on Boundless's default variables.

    Install

    npm i boundless-tokenized-input

    DownloadsWeekly Downloads

    2

    Version

    1.1.0

    License

    MIT

    Last publish

    Collaborators

    • sighrobot