React TokenInput
Live Demo: https://seawind543.github.io/react-token-input/
React TokenInput (react-customize-token-input)
A react token (tag) controlled
input component, which support:
- Accept customize data structure.
- Customize token (tag) Look & Feel on the
label
Demo, delete button
Demo, or even override the whole Token component
Demo. - Customize separate characters to separate the end-user input string. Demo
- Inline editing on exist token.
- Paste values. Demo
- Preprocessing function to normalized user input value.
It could be helpful to reproduce a single value into multiple values too. Demo
- Validate function.
Installation
- Install the latest version of react and react-customize-token-input:
yarn add react react-customize-token-input
- At this point you can import
react-customize-token-input
and its styles in your application by:
import TokenInput from 'react-customize-token-input';
import 'react-customize-token-input/dist/react-customize-token-input.css';
Dev
- Run
yarn install
to install required packages. - Run
yarn dev
to launch webpack-dev-server
. - After step 2, you will see following message output in command console.
「wds」: Project is running at http://0.0.0.0:8000/
「wds」: webpack output is served from /
「wds」: Content not from webpack is served from ../docs
Note: To stop the program, just type ctrl + c
in command console.
- After step 3 complete, you could access
http://localhost:8000/
to see result.
Usage
See Live Examples: https://seawind543.github.io/react-token-input/
Note: Sources code of Examples in the folder examples/
Props
interface TokenInputProps<ValueType = string, ErrorType = string> {
style?: CSSProperties;
className?: string;
placeholder?: string;
readOnly?: boolean;
disableCreateOnBlur?: boolean;
autoFocus?: boolean;
tokenValues: ValueType[];
separators?: TokenSeparator[];
specialKeyDown?: SpecialKeyDownConfig;
onInputValueChange?: OnInputValueChange;
onPreprocess?: OnPreprocess;
onTokenValueValidate?: OnTokenValueValidate<ValueType, ErrorType>;
onTokenValuesChange?: OnTokenValuesChange<ValueType>;
onBuildTokenValue?: OnBuildTokenValue<ValueType>;
customizeTokenComponent?: (
props: TokenProps<ValueType, ErrorType>
) => ReactElement | null;
onGetTokenClassName?: OnGetTokenClassName<ValueType, ErrorType>;
onGetTokenDisplayLabel?: OnGetTokenDisplayLabel<ValueType, ErrorType>;
onRenderTokenDeleteButtonContent?: OnRenderTokenDeleteButtonContent;
onGetIsTokenEditable?: OnGetIsTokenEditable<ValueType, ErrorType>;
onGetTokenEditableValue?: OnGetTokenEditableValue<ValueType, ErrorType>;
onGetTokenErrorMessage?: OnGetTokenErrorMessage<ValueType, ErrorType>;
onCreatorFocus?: React.FocusEventHandler<HTMLInputElement>;
onCreatorBlur?: React.FocusEventHandler<HTMLInputElement>;
onCreatorKeyDown?: React.KeyboardEventHandler<HTMLInputElement>;
}
Methods in ref of TokenInput
TokenInput provide the following method in the ref of it.
Method | Description | Parameter | Return |
---|
focus | Set focus on TokenInput. It will focus on the creator not the inline-editor | Same as HTMLElement.focus() | void |
setCreatorValue | Set value of TokenCreator | value: string | void |
getCreatorValue | Get value of TokenCreator | void | string |
createTokens | Trigger tokens create. If param.value undefined, then apply the value of TokenCreator directly. | value?: string | void |
Could reference Demo, and its source code ExampleRefMethods
in the folder examples/
.
If you are using TypeScript, reference the code below for the typing of useRef.
import TokenInput, { type TokenInputRef } from 'react-customize-token-input';
const tokenInputRef = useRef<TokenInputRef>(null);
const handleFocusButtonClick = () => {
tokenInputRef.current?.focus();
}
<TokenInput
ref={tokenInputRef}
tokenValues={values}
onTokenValuesChange={setValues}
/>
Predefined KeyDown Event Handlers
TokenInput has the following Predefined KeyDown event handlers.
For Token Create
KeyDown | Description | Note |
---|
Backspace | In case the current inputValue is an empty string , the latest token in the list tail will be deleted. | |
Escape | Clear the input-box's value. | A.K.A. Reset. |
Enter | Create a token with the inputValue and continually focused on the inputBox for the next inputting. | |
Tab | Same as onEnter. | - Default not apply
- Under Beta
|
For Inline editing
KeyDown | Description | Note |
---|
Escape | End editing without change the value of the token. | A.K.A. Reset |
Enter | End editing and apply the new value. In case the new value is an empty string , will perform the onEscape . | |
Default value of the optional Props
style = undefined,
className = undefined,
placeholder = undefined,
readOnly = false,
disableCreateOnBlur = undefined,
autoFocus = false,
separators = DEFAULT_SEPARATORS,
specialKeyDown = DEFAULT_SPECIAL_KEY_DOWN_CONFIG,
onInputValueChange = undefined,
onPreprocess = undefined,
onTokenValueValidate = defaultTokenValueValidate,
onTokenValuesChange = undefined,
onBuildTokenValue = defaultBuildTokenValue,
customizeTokenComponent = undefined,
onGetTokenClassName = undefined,
onGetTokenDisplayLabel = defaultGetTokenEditableValue,
onRenderTokenDeleteButtonContent = undefined,
onGetIsTokenEditable = defaultGetIsTokenEditable,
onGetTokenEditableValue = defaultGetTokenEditableValue,
onGetTokenErrorMessage = defaultGetTokenErrorMessage,
Props of customizeTokenComponent
Your CustomizeTokenComponent will receive these props from TokenInput. You could decide where & how to use them to customize
your Token component.
Could also reference this Demo and its source code ExampleCustomizeToken
in the folder examples/
.
export interface TokenProps<ValueType = string, ErrorType = string> {
readOnly: boolean;
tokenValue: ValueType;
tokenMeta: TokenMeta<ErrorType>;
onGetClassName?: OnGetTokenClassName<ValueType, ErrorType>;
onGetDisplayLabel: OnGetTokenDisplayLabel<ValueType, ErrorType>;
onRenderDeleteButtonContent?: OnRenderTokenDeleteButtonContent;
onGetIsEditable: OnGetIsTokenEditable<ValueType, ErrorType>;
onGetEditableValue: OnGetTokenEditableValue<ValueType, ErrorType>;
onBuildTokenValue: OnBuildTokenValue<ValueType>;
onGetErrorMessage: OnGetTokenErrorMessage<ValueType, ErrorType>;
onEditStart: () => void;
onEditEnd: (newTokenValue?: ValueType) => void;
onDelete: () => void;
}
License
MIT