react-dadata-box

README LANGUAGE

Russian | English

---

React component for use DaData service API (suggestions) implemented as input with dropdown suggestions list, with auto-fetch data at user input. It provides user-friendly navigation from keyboard in addition to mouse click.

DaData service oriented to Russian Federation and russian-speaking users with russian queries. It use FIAS and KLADR and other national registry's and datasets, it provides suggestions only on russian language.

Demo

(at top of demo showed keystrokes captured by keycastr MacOS application)

DatData service is shareware, to use API you need token (person/organization). For personal use, you need to have Account, your token lets you to have 10000 free API call's per day.

Installation

npm install react-dadata-box

Usage

1import ReactDadataBox from 'react-dadata-box';
2
3// ...
4
5<ReactDadataBox token="API_KEY" query="Москва" />

Properties

allowClear

1allowClear?: boolean;

show 'clear value' ui control's (at clear - change handlers are called)

---

autocomplete

1autocomplete?: 'on' | 'off';

autocomplete prop for input primitive

---

customActions

function that returns node (or nodes array) to place that as 'custom action' (each component from result placed in separated block at the end of list)

at v1.3.4 variant 'React.ReactNode' deprecated at types definition
since v1.3.5 variant 'React.ReactNode' will be deprecated from functionality

1import { SpecificQueryModeResponse, FetchType } from 'react-dadata-box';
2
3// {SpecificQueryModeResponse<T>} where 'T' is one of FetchType (value placed at 'type' prop):
4// {AddressQueryMode} 'address' | {CountryQueryMode} 'country' | {PartyQueryMode} 'party' | 
5// {BankQueryMode} 'bank' | {EmailQueryMode} 'email' | {FioQueryMode} 'fio' | 
6// {FmsUnitQueryMode} 'fms_unit';
7 
8// SpecificQueryModeResponse<FetchType> is generic that returned one of corresponding AbstractResponseType
9// AbstractResponseType and any of response types is built-in and may be impoted from library
10type AbstractResponseType = CountryResponseType | PartyResponseType | BankResponseType | EmailResponseType | FioResponseType | FmsUnitResponseType
11
12// type of 'suggestions' wiil be infered automaticaliy from fetch type and it will be SpecificQueryModeResponse<T>[]
13customActions?: ((suggestions: SpecificQueryModeResponse<FetchType>[]) => React.ReactNode);

at versions < v1.3.4

1// {DadataSuggestion} always typed responce as 'address' query { AddressResponseType }
2customActions?: ((suggestions: DadataSuggestion[]) => React.ReactNode) | React.ReactNode;

---

customStyles

custom styling for embedded nodes: suggestion list, single suggestion, note and custom-action. Map-object, where key is native css classname of target node, and value is string interpreted as additional class name, or object with styles to place it into style property of target node primitive

1  customStyles?: {
2    'react-dadata__custom-action'?: string | React.CSSProperties;
3    'react-dadata__suggestion'?: string | React.CSSProperties;
4    'react-dadata__suggestion-note'?: string | React.CSSProperties;
5    'react-dadata__suggestions'?: string | React.CSSProperties;
6  }

---

customEndpoint

custom URI for fetching DaData service (when that placed behind the proxy, or service deployed locally in your infrastructure). It may be string that interpreted as path where available DaData service root (api call will added automatically) or it may be a object with 'host' or/and 'api' properties that interpreted respectively as DaData service root and api-call replacement

1customEndpoint?: string | { host?: string; api?: string };

1{
2  host: 'https://suggestions.dadata.ru',
3  api: 'suggestions/api/4_1/rs/suggest'
4}

---

customInput

function that get as argument user input, for replace embedded input primitive by custom or other component with compatible props signature

1interface BaseInputProps<T = HTMLInputElement> {
2  autoComplete: boolean | 'off';
3  className: string;
4  onBlur: React.FocusEventHandler<T>;
5  onChange: React.ChangeEventHandler<T>;
6  onFocus: React.FocusEventHandler<T>;
7  onKeyDown: React.KeyboardEventHandler<T>;
8  placeholder: string;
9  value: string;
10}
11...
12customInput?: (props: BaseInputProps) => React.ReactNode;

---

debounce

debouncing interval for fetching data at user input in miliseconds

1debounce?: number;

---

onChange

change/select event handler, called when user select suggestion by mouse click or Enter key from keyboard. Handler gets suggestion object as argument

1import { SpecificQueryModeResponse, FetchType } from 'react-dadata-box';
2
3// {SpecificQueryModeResponse<T>} where 'T' is one of FetchType (value placed at 'type' prop):
4// {AddressQueryMode} 'address' | {CountryQueryMode} 'country' | {PartyQueryMode} 'party' | 
5// {BankQueryMode} 'bank' | {EmailQueryMode} 'email' | {FioQueryMode} 'fio' | 
6// {FmsUnitQueryMode} 'fms_unit';
7
8// SpecificQueryModeResponse<FetchType> is generic that returned one of corresponding AbstractResponseType
9// AbstractResponseType and any of response types is built-in and may be impoted from library
10
11type AbstractResponseType = CountryResponseType | PartyResponseType | BankResponseType | EmailResponseType | FioResponseType | FmsUnitResponseType
12
13// type of 'suggestion' wiil be infered automaticaliy from fetch type and it will be SpecificQueryModeResponse<T>[]
14onChange?: (suggestion: SpecificQueryModeResponse<FetchType>) => void;

---

onBlur

handler called on blur event of react-dadata-box input (also at closing list after user selection or outside click) this handler extended by second argument that contains current query text

1onBlur?: (event: SyntheticEvent<HTMLInputElement, FocusEvent>, query: string) => void;

---

onIdleOut

handler called when by current query, service return nothing variants of suggestion. Handler gets current query string as argument

1 onIdleOut?: (query: string) => void;

---

payloadModifier

patch for payload object (that sended to DaData service). It may be function that returns patch object that will be spread on native generated payload, or it may be object that permanently spread on native payload at each call. (it allows use difficult filters and additional parameters available for DaData API but not implemented in interface of this component)

1interface BasePayload {
2  query: string;
3  count?: number;
4}
5...
6object | ((payload: BasePayload) => BasePayload & object);

---

placeholder

placeholder text for input (it placed into relevant prop of target input)

1placeholder?: string;

---

query

query string for fetch suggestion from DaData service

1query?: string;

---

showNote

show at the top of suggestions list with help note about available keyboard actions

1showNote?: boolean;

---

silentQuery

special query string alternative that used when directly query prop is undefined or is empty string. It query will not be show in input node, but it determine of available suggestions in list at component on focus. (if directly query defined and not empty, this is ignored)

1silentQuery?: string;

---

silentInit

function that may be used to autoselect from preventive fetched (by placed query or silentQuery), it called with list of fetched suggestions, and if it will return index, appropriate suggestion will be selected (all handlers fire as at user select)

1silentInit?: (suggestions: DadataSuggestion[]) => number | undefined;

---

token

auth token for DaData service

1token: string;

---

type

fetched suggestions type (declarative in DaData service terms).

It may be 'address', 'country', 'bank', 'email', 'fio' (last/first/middle names + gender detection), 'fms_unit' (branch/unit that issued Russian pasport)

1type FetchType = AddressQueryMode | CountryQueryMode | PartyQueryMode | BankQueryMode | EmailQueryMode | FioQueryMode | FmsUnitQueryMode;
2// => 'address' (default) | 'country' | 'party' | 'bank' | 'email' | 'fio' | 'fms_unit'
3type?: FetchType;

For correct infer types results of fetching, you need to manually setup type string to component generic parameter: 'address' is default typing it not need to be placed patently

1// for example if we need to fetch 'party'
2import { SpecificQueryModeResponse } from 'react-dadata-box';
3...
4// if you setup 'party' as generic param - handlers as 'onChange' will be typed accordingly
5// (suggestion: PartyResponseType) => void  in this sample
6<ReactDadataBox<'party'>
7    token={testToken}
8    type='party'
9    // 'suggestion' type will be automatically infered as : SpecificQueryModeResponse<'party'>
10    onChange={(suggestion) => setSample2(suggestion)}
11    // 'suggestion' type will be automatically infered as : SpecificQueryModeResponse<'party'>
12    customActions={(suggestions) =>
13        !suggestions.length && (
14            <a href=" " onClick={idleAction}>
15              произвольное действие
16            </a>
17        )
18    }
19/>

exported bulit-in types accordingly to type parameter

type param	built-in type
'address'	AddressResponseType (default)
'country'	CountryResponseType
'party'	PartyResponseType
'bank'	BankResponseType
'email'	EmailResponseType
'fio'	FioResponseType
'fms_unit'	FmsUnitResponseType

---

forceOpenList

this property force the already opened suggestions list will be permanently open, prevents close list by Blur event or user select value Action (it also is way may to debug suggestions) Attention! if query is empty and not declared any customActions - list is truthy empty of elements (empty list couldn't be open even if forceOpenList === true)

1forceOpenList?: boolean;