@npm.tangocode/tc_ui_components
Version:
[<img src="https://s3.amazonaws.com/tc-ui-components/documentationImages/tangoCodeLogo.png">](https://tangocode.com/) # TangoCode React UI Components #
110 lines (81 loc) • 6.35 kB
Markdown
## Token Suggest ##
### Description ###
An easily stylable React select / token / autocomplete
### Props ###
1. __customInput ?__ (any) : If you have your own custom input component you can use it with this prop
2. __customInputProps ?__ (any) : The props for the custom input
3. __customEmptyStateMessage ?__ (JSX.Element) : A JSX Element to be shown in the drop down, in case there are no options to show. The element will be shown exactly as passed.
4. __defaultAfterToken ?__ (string) : A string that is added automatically after the token is closed. The default value is a space.
5. __emptyStateMessage ?__ (string) : A string to be shown in the drop down, in case there are no options to show. The message will be shown with a default style, but it can be changed (see prop styles).
6. __initialSuggestOptions__ ({ toString: () => string }[]) : The definition of all posible suggestions. It supports a list of anything that can be transformed in a string using the function toString() (['a', 'b', 'c'] is a valid value). The component takes care of filtering the suggestions, depending on the input. The options will only show after the user types the token opener.
7. __inputValue__ (string) : The value to be shown in the input. It is used also to filter the suggestions.
8. __onEnterKeyPressed ?__ (() => void) : Function to be called every time the user hits Enter, but not for selecting an option. If the drop down is displayed, and an option is focused, hitting Enter doesn't trigger this function.
9. __onValueChange__ ((value: string, isValid: boolean) => void) : Function to be called when the input changes. It passes the new value and a boolean if it is valid or not (tokens are correctly defined and valid).
10. __optionMatches ?__ ((option: { toString: () => string }, currentValue: string) => boolean) : Function to be called every time the input value changes and the token opener typed, in order to filter the suggestions. The function is called for each option in the initialSuggestOptions. It receives an option and the current input value, returning true if it is matches and should be shown. By default, function startsWith is used (case insensitive).
11. __placeholder ?__ (string) : Placeholder for the input.
12. __readOnly ?__ (boolean) : Indicates whether the input is editable or not. If not, the drop down will never be displayed. By default, it is false.
13. __showDropDownOnEmpty ?__ (boolean) : Indicates whether the drop down will be shown when no suggestions match the input value or not. Use in true when passing an empty state message. By default, it is false.
14. __styles ?__ (TokenSuggest.Styles) : Custom stylings that will overwrite the default styles. Must be an object of styled components with properties that match one or several of the options below.
* InputDropDownDrawer is the component used inside InputSuggest that renders the input and the drop down.
* Container is a div that has all the content of InputDropDownDrawer.
* Input is the input where the user types.
* InputWrapper is a div that contains the Input.
* DropDownDrawer is a component used inside InputDropDownDrawer that renders the drop down.
* Container is a div that has all the content of DropDownDrawer.
* List is a ul that has all the options (li).
* DropDownEmptyState is a component used inside DropDownDrawer that renders the empty state message.
* Container is a div that has all the content of DropDownEmptyState.
* Message is a div that styles the emptyStateMessage.
* DropDownItem is a component used inside DropDownDrawer that renders an option.
* HighlightedItemChunk is a span that contains the highlighted parts of the option.
* ListItemFocused is a div that has all the content of DropDownItem when the option is focused.
* ListItemNotFocused is a div that has all the content of DropDownItem when the option is not focused.
* RegularItemChunk is a span that contains the regular parts of the option.
```ts
InputDropDownDrawer: {
Container: <styled component>;
Input: <styled component>;
InputWrapper: <styled component>;
DropDownDrawer: {
Container: <styled component>;
List: <styled component>;
DropDownEmptyState: {
Container: <styled component>;
Message: <styled component>;
};
DropDownItem: {
HighlightedItemChunk: <styled component>;
ListItemFocused: <styled component>;
ListItemNotFocused: <styled component>;
RegularItemChunk: <styled component>;
};
};
};
```
15. __tokenCloser ?__ (string) : Indicates the token closer. The default value is '>'.
16. __tokenOpener ?__ (string) : Indicates the token opener. The default value is '<'.
17. __id ?__ (string): A prefix id for all the html elements of the component
18. __name ?__ (string): A prefix name for all the html elements of the component
### Usage ###
The initial state of the component just shows the input. The drop down is displayed once the user types the token opener inside the input. After that, the following features are available:
When pressing Arrow Down or Arrow Up, the drop down is displayed, switching the focused option.
When pressing Enter when an option is focused, the drop down is closed and the component notifies that the new value should be the option selected.
When pressing Escape or Tab when the drop down is being displayed, the drop down is not displayed anymore.
The following Input Suggest was created with the props:
```jsx
<div style={{ width: '200px' }}>
<TokenSuggest
initialSuggestOptions={[
'AdHeadline',
'AdDescription',
'ClientAddress',
'ClientName',
'ClientUrl'
]}
inputValue={this.state.value}
onValueChange={(value: string) => { this.setState({ value }) }}
/>
</div>
```
Resulting, after typing 'Visit us on <C', in the render of:
