Infer React SDK

Un componente pronto all'uso e un hook headless per la Sua UI.

@pro6pp/infer-react0.1.0-beta.31Licenza MIT
npmCodice sorgente su GitHub

<Pro6PPInfer />

A styled React component for Pro6PP Infer API. Includes styling, keyboard navigation, and loading states.

Inoltra il suo ref all'elemento HTMLInputElement.

PropsPro6PPInferProps

Da InferConfig in @pro6pp/infer-core
countryCountryCodeObbligatorioImposta il percorso API

The country to perform address lookups in.

authKeystringParametro API

Your Pro6PP Authorization Key. Optional if using a proxy.

limitnumberParametro API

Number of suggestions to request per batch, at most 1000. 0 uses the default.

Predefinito
20
languageLanguageCodeParametro API

Language code for response labels. Affects the language of returned address labels. Only applicable for BE country code.

sortSortOrderParametro API

Sort mixed address and place suggestions by relevance or distance. Distance sorting requires the Infer Extended (infer::location) capability. It measures from lat and lng when provided, otherwise from the approximate location of the request IP, and sorts by relevance when neither is available.

Predefinito
'relevance'
latnumberParametro API

Latitude of the origin used for distance sorting, sent only when sort is 'distance'. When provided, lng must also be provided.

lngnumberParametro API

Longitude of the origin used for distance sorting, sent only when sort is 'distance'. When provided, lat must also be provided.

typesInferTypes

Suggestion types to request. Omit this to preserve the address-only default.

apiUrlstring

If provided, this URL is used as the API endpoint. The query params are appended, including country in lowercase.

  • If not provided, the SDK defaults to 'https://api.pro6pp.nl/v2/infer/{country}'.
fetcherFetcher

Custom fetch implementation for network requests.

Predefinito
globalThis.fetch
debounceMsnumber

The delay in milliseconds before performing the API search. Note: A lower bound of 50ms is enforced to protect API stability.

Predefinito
150
maxRetriesnumber

Maximum number of retry attempts after a network error or a 5xx or 429 response. Valid range: 0 to 10.

Predefinito
0
onStateChange(state: InferState) => void

Callback triggered whenever the internal state (suggestions, loading status, etc.) updates.

onSelect(selection: AddressValue | string | null) => void

Callback triggered when an address selection completes or is cleared. Receives the AddressValue of the selected address, or its label as a string when the selection has no structured value. Receives null when the user edits a completed selection or selects a place after a structured address. Partial selections, such as a city or street, do not trigger it.

onPlaceSelect(selection: PlaceValue | null) => void

Callback triggered when a point of interest is selected, or with null when the user edits the selected place or selects an address instead.

Da UseInferConfig in @pro6pp/infer-react
initialValueAddressValue

Initial address value to pre-fill the state with. Pre-filling does not call onSelect or onStateChange.

Da Pro6PPInferProps in @pro6pp/infer-react
classNamestring

Optional CSS class for the wrapper div.

styleReact.CSSProperties

Optional inline styles for the wrapper div.

inputPropsReact.InputHTMLAttributes<HTMLInputElement>

Attributes to pass directly to the underlying input element. className is added to pro6pp-input, onChange, onKeyDown and onFocus run after the component's own handlers, and value is ignored because the component controls it.

placeholderstring

Custom placeholder text.

Predefinito
'Start typing an address...'
renderItem(item: InferResult, isActive: boolean) => React.ReactNode

A custom render function for individual suggestion items.

disableDefaultStylesboolean

If true, prevents the default CSS theme from being injected.

Predefinito
false
noResultsTextstring

The text to show when no results are found.

Predefinito
'No results found'
loadingTextstring

The text to show on the bottom loading indicator.

Predefinito
'Loading more...'
searchingTextstring

Text displayed while the initial search is pending. Defaults to Searching....

clearInputLabelstring

Accessible name for the clear button. Defaults to Clear input.

renderNoResults(state: InferState) => React.ReactNode

A custom render function for the "no results" state.

showClearButtonboolean

If true, shows a clear button when the input is not empty.

Predefinito
true

useInfer

TypeScript
function useInfer(config: UseInferConfig): { state, core, inputProps, selectItem, setValue, setPlace, loadMore }

A headless React hook that provides the logic for address search using the Infer API.

config UseInferConfigThe engine configuration (authKey, country, etc.).
RestituisceAn object containing the current state, the core instance, and pre-bound input props.

Restituisce

stateInferState

The current UI state (suggestions, loading status, query, value, etc.).

coreInferCore

The raw InferCore instance for manual control.

inputProps{ value: string; onChange: (e: React.ChangeEvent<HTMLInputElement>) => void; onKeyDown: (e: React.KeyboardEvent<HTMLInputElement>) => void; }

Pre-configured event handlers to spread onto an <input /> element.

selectItem(item: InferResult | string) => boolean

Manually select a specific suggestion.

setValue(address: AddressValue) => void

Programmatically set the address value.

setPlace(place: PlaceValue) => void

Programmatically set a selected place value.

loadMore() => void

Load more results.

Classi CSS

18 classi
ClasseDescrizione
.pro6pp-wrapperThe container element wrapping the input and dropdown.
.pro6pp-inputThe input element itself.
.pro6pp-input-addonsThe container for the controls inside the input, such as the clear button.
.pro6pp-clear-buttonThe button that clears the input.
.pro6pp-dropdownThe panel containing the suggestion list and the loader.
.pro6pp-listThe <ul> list containing the suggestions.
.pro6pp-itemA single suggestion item (<li>).
.pro6pp-item--activeThe currently highlighted item (for keyboard navigation).
.pro6pp-item__labelThe main text/label of a suggestion.
.pro6pp-item--placeAn item for a point of interest rather than an address.
.pro6pp-item__label--matchThe part of a label that matches the query.
.pro6pp-item--fuzzyAn item for a close match rather than an exact one.
.pro6pp-item__label--unmatchedThe rest of the label.
.pro6pp-item__subtitleThe secondary text (e.g., city or result count).
.pro6pp-item__chevronThe icon indicating a folder/expandable result.
.pro6pp-no-resultsThe message shown while searching or when no suggestions are found.
.pro6pp-loader-itemThe element containing the loading spinner and text.
.pro6pp-mini-spinnerThe spinner icon inside the loader item.

Esportati anche

Riesportato da @pro6pp/infer-core.

INFER_PLACES_COUNTRIESreadonly ["NL", "BE", "DE", "FR", "AT", "ES", "DK", "LU", "IT"]

Countries currently supported by the Infer API for place suggestions.

getOrderedItems(state)→ InferResult[]

Returns suggestions in the order intended for display and keyboard navigation. Mixed and place responses provide the ranked order in suggestions. If that list is empty, fall back to the separate category arrays.

state InferState
supportsInferPlaces(country)→ boolean

Returns whether the Infer API supports place suggestions for a country. Country codes are compared case-insensitively after trimming whitespace.

country string

Tipi

Pro6PPInferPropsinterface

Props for the Pro6PPInfer component.

authKeystring

Your Pro6PP Authorization Key. Optional if using a proxy.

countryCountryCodeObbligatorio

The country to perform address lookups in.

apiUrlstring

If provided, this URL is used as the API endpoint. The query params are appended, including country in lowercase.

  • If not provided, the SDK defaults to 'https://api.pro6pp.nl/v2/infer/{country}'.
fetcherFetcher

Custom fetch implementation for network requests.

Predefinito
globalThis.fetch
limitnumber

Number of suggestions to request per batch, at most 1000. 0 uses the default.

Predefinito
20
debounceMsnumber

The delay in milliseconds before performing the API search. Note: A lower bound of 50ms is enforced to protect API stability.

Predefinito
150
maxRetriesnumber

Maximum number of retry attempts after a network error or a 5xx or 429 response. Valid range: 0 to 10.

Predefinito
0
languageLanguageCode

Language code for response labels. Affects the language of returned address labels. Only applicable for BE country code.

sortSortOrder

Sort mixed address and place suggestions by relevance or distance. Distance sorting requires the Infer Extended (infer::location) capability. It measures from lat and lng when provided, otherwise from the approximate location of the request IP, and sorts by relevance when neither is available.

Predefinito
'relevance'
latnumber

Latitude of the origin used for distance sorting, sent only when sort is 'distance'. When provided, lng must also be provided.

lngnumber

Longitude of the origin used for distance sorting, sent only when sort is 'distance'. When provided, lat must also be provided.

typesInferTypes

Suggestion types to request. Omit this to preserve the address-only default.

onStateChange(state: InferState) => void

Callback triggered whenever the internal state (suggestions, loading status, etc.) updates.

onSelect(selection: AddressValue | string | null) => void

Callback triggered when an address selection completes or is cleared. Receives the AddressValue of the selected address, or its label as a string when the selection has no structured value. Receives null when the user edits a completed selection or selects a place after a structured address. Partial selections, such as a city or street, do not trigger it.

onPlaceSelect(selection: PlaceValue | null) => void

Callback triggered when a point of interest is selected, or with null when the user edits the selected place or selects an address instead.

initialValueAddressValue

Initial address value to pre-fill the state with. Pre-filling does not call onSelect or onStateChange.

classNamestring

Optional CSS class for the wrapper div.

styleReact.CSSProperties

Optional inline styles for the wrapper div.

inputPropsReact.InputHTMLAttributes<HTMLInputElement>

Attributes to pass directly to the underlying input element. className is added to pro6pp-input, onChange, onKeyDown and onFocus run after the component's own handlers, and value is ignored because the component controls it.

placeholderstring

Custom placeholder text.

Predefinito
'Start typing an address...'
renderItem(item: InferResult, isActive: boolean) => React.ReactNode

A custom render function for individual suggestion items.

disableDefaultStylesboolean

If true, prevents the default CSS theme from being injected.

Predefinito
false
noResultsTextstring

The text to show when no results are found.

Predefinito
'No results found'
loadingTextstring

The text to show on the bottom loading indicator.

Predefinito
'Loading more...'
searchingTextstring

Text displayed while the initial search is pending. Defaults to Searching....

clearInputLabelstring

Accessible name for the clear button. Defaults to Clear input.

renderNoResults(state: InferState) => React.ReactNode

A custom render function for the "no results" state.

showClearButtonboolean

If true, shows a clear button when the input is not empty.

Predefinito
true
UseInferConfiginterface

Extended configuration for the React hook.

authKeystring

Your Pro6PP Authorization Key. Optional if using a proxy.

countryCountryCodeObbligatorio

The country to perform address lookups in.

apiUrlstring

If provided, this URL is used as the API endpoint. The query params are appended, including country in lowercase.

  • If not provided, the SDK defaults to 'https://api.pro6pp.nl/v2/infer/{country}'.
fetcherFetcher

Custom fetch implementation for network requests.

Predefinito
globalThis.fetch
limitnumber

Number of suggestions to request per batch, at most 1000. 0 uses the default.

Predefinito
20
debounceMsnumber

The delay in milliseconds before performing the API search. Note: A lower bound of 50ms is enforced to protect API stability.

Predefinito
150
maxRetriesnumber

Maximum number of retry attempts after a network error or a 5xx or 429 response. Valid range: 0 to 10.

Predefinito
0
languageLanguageCode

Language code for response labels. Affects the language of returned address labels. Only applicable for BE country code.

sortSortOrder

Sort mixed address and place suggestions by relevance or distance. Distance sorting requires the Infer Extended (infer::location) capability. It measures from lat and lng when provided, otherwise from the approximate location of the request IP, and sorts by relevance when neither is available.

Predefinito
'relevance'
latnumber

Latitude of the origin used for distance sorting, sent only when sort is 'distance'. When provided, lng must also be provided.

lngnumber

Longitude of the origin used for distance sorting, sent only when sort is 'distance'. When provided, lat must also be provided.

typesInferTypes

Suggestion types to request. Omit this to preserve the address-only default.

onStateChange(state: InferState) => void

Callback triggered whenever the internal state (suggestions, loading status, etc.) updates.

onSelect(selection: AddressValue | string | null) => void

Callback triggered when an address selection completes or is cleared. Receives the AddressValue of the selected address, or its label as a string when the selection has no structured value. Receives null when the user edits a completed selection or selects a place after a structured address. Partial selections, such as a city or street, do not trigger it.

onPlaceSelect(selection: PlaceValue | null) => void

Callback triggered when a point of interest is selected, or with null when the user edits the selected place or selects an address instead.

initialValueAddressValue

Initial address value to pre-fill the state with. Pre-filling does not call onSelect or onStateChange.

AddressSuggestioninterface

A regular address or partial-address suggestion.

labelstringObbligatorio

The text to display in the UI (e.g. "Main Street").

subtitlestring | null

Secondary information (e.g. city name when suggesting a street).

countnumber | string

Number of underlying results found for this suggestion.

exactboolean

False for close (fuzzy) matches that top up the exact matches.

matched_valuestring | null

The lowercase name the fuzzy pass matched, for close matches.

diff_positionsnumber[] | null

0-based query positions that differ from the match, for close matches.

valueAddressValue | string

The actual address data, when this result completes an address.

type'address'

Address suggestions may omit this field, as in existing API responses.

AddressValueinterface

The standardized address object returned upon a successful final selection.

streetstringObbligatorio

The name of the street.

citystringObbligatorio

The name of the city/locality.

latnumber | null

Latitude of the address location.

lngnumber | null

Longitude of the address location.

street_numberstring | number

The street number.

postcodestring

The postal code.

additionstring | null

The street number addition or suffix.

[key: string]unknown

Allow for extra fields if API expands.

CountryCodetype

Supported ISO 3166-1 alpha-2 country codes.

TypeScript
type CountryCode = 'NL'
  | 'DE'
  | 'BE'
  | 'AT'
  | 'DK'
  | 'CH'
  | 'LU'
  | 'FR'
  | 'ES'
  | 'GB'
  | 'IT'
  | (string & {});
Fetchertype

Custom fetch implementation, compatible with the Web Fetch API.

Custom fetch implementation, compatible with the Web Fetch API. Useful for Node.js environments or proxying requests.

TypeScript
type Fetcher = (input: RequestInfo
  | URL, init?: RequestInit) => Promise<Response>;
InferConfiginterface

Configuration options for the Infer engine.

authKeystring

Your Pro6PP Authorization Key. Optional if using a proxy.

countryCountryCodeObbligatorio

The country to perform address lookups in.

apiUrlstring

If provided, this URL is used as the API endpoint. The query params are appended, including country in lowercase.

  • If not provided, the SDK defaults to 'https://api.pro6pp.nl/v2/infer/{country}'.
fetcherFetcher

Custom fetch implementation for network requests.

Predefinito
globalThis.fetch
limitnumber

Number of suggestions to request per batch, at most 1000. 0 uses the default.

Predefinito
20
debounceMsnumber

The delay in milliseconds before performing the API search. Note: A lower bound of 50ms is enforced to protect API stability.

Predefinito
150
maxRetriesnumber

Maximum number of retry attempts after a network error or a 5xx or 429 response. Valid range: 0 to 10.

Predefinito
0
languageLanguageCode

Language code for response labels. Affects the language of returned address labels. Only applicable for BE country code.

sortSortOrder

Sort mixed address and place suggestions by relevance or distance. Distance sorting requires the Infer Extended (infer::location) capability. It measures from lat and lng when provided, otherwise from the approximate location of the request IP, and sorts by relevance when neither is available.

Predefinito
'relevance'
latnumber

Latitude of the origin used for distance sorting, sent only when sort is 'distance'. When provided, lng must also be provided.

lngnumber

Longitude of the origin used for distance sorting, sent only when sort is 'distance'. When provided, lat must also be provided.

typesInferTypes

Suggestion types to request. Omit this to preserve the address-only default.

onStateChange(state: InferState) => void

Callback triggered whenever the internal state (suggestions, loading status, etc.) updates.

onSelect(selection: AddressValue | string | null) => void

Callback triggered when an address selection completes or is cleared. Receives the AddressValue of the selected address, or its label as a string when the selection has no structured value. Receives null when the user edits a completed selection or selects a place after a structured address. Partial selections, such as a city or street, do not trigger it.

onPlaceSelect(selection: PlaceValue | null) => void

Callback triggered when a point of interest is selected, or with null when the user edits the selected place or selects an address instead.

InferPlacesCountryCodetype
TypeScript
type InferPlacesCountryCode = (typeof INFER_PLACES_COUNTRIES)[number];
InferResulttype

A single item in the suggestion list.

TypeScript
type InferResult = AddressSuggestion
  | PlaceSuggestion;
InferStateinterface

The complete UI state managed by InferCore.

querystringObbligatorio

The current text value of the search input.

stageStage | nullObbligatorio

The current logical stage of the address lookup.

citiesInferResult[]Obbligatorio

List of city suggestions (used in mixed stage).

streetsInferResult[]Obbligatorio

List of street suggestions (used in mixed stage).

suggestionsInferResult[]Obbligatorio

General list of suggestions for the current stage.

placesPlaceSuggestion[]Obbligatorio

Place suggestions: the separate places list of the API response, or otherwise the place suggestions in suggestions.

isValidbooleanObbligatorio

Flag indicating if the current selection is complete and valid.

valueAddressValue | nullObbligatorio

The selected address value, otherwise null (places use selectedPlace).

selectedPlacePlaceValue | nullObbligatorio

The selected place object, otherwise null.

isErrorbooleanObbligatorio

Flag indicating if the last API request failed.

isLoadingbooleanObbligatorio

Flag indicating if a network request is currently in progress.

hasMorebooleanObbligatorio

Flag indicating if more results are available to load.

selectedSuggestionIndexnumberObbligatorio

The index of the currently highlighted suggestion.

  • 0 to n: An item is highlighted via keyboard navigation.
  • -1: No item is highlighted.
InferTypestype

The kinds of suggestions requested from the Infer API.

The kinds of suggestions requested from the Infer API.

When omitted, the API keeps its address-only default.

TypeScript
type InferTypes = 'address'
  | 'place'
  | 'address,place';
LanguageCodetype

Supported language codes for address labels.

TypeScript
type LanguageCode = 'nl'
  | 'fr'
  | 'de'
  | (string & {});
PlaceSuggestioninterface

A suggestion that represents a point of interest rather than an address.

labelstringObbligatorio

The text to display in the UI (e.g. "Main Street").

subtitlestring | null

Secondary information (e.g. city name when suggesting a street).

countnumber | string

Number of underlying results found for this suggestion.

exactboolean

False for close (fuzzy) matches that top up the exact matches.

matched_valuestring | null

The lowercase name the fuzzy pass matched, for close matches.

diff_positionsnumber[] | null

0-based query positions that differ from the match, for close matches.

type'place'Obbligatorio

Marks the suggestion as a point of interest.

valuePlaceValueObbligatorio

The place data.

PlaceValueinterface

A point of interest returned by the Infer API.

place_idstringObbligatorio

Stable identifier of the place in the source dataset.

namestringObbligatorio

Display name of the place.

categorystringObbligatorio

Primary place category.

formatted_addressstring | nullObbligatorio

Human-readable address, when available.

streetstring | nullObbligatorio

Street name, when available.

street_numbernumber | nullObbligatorio

Street number, when available.

additionstring | nullObbligatorio

Street number addition, when available.

postcodestring | nullObbligatorio

Postal code, when available.

citystring | nullObbligatorio

City name, when available.

latnumberObbligatorio

Latitude of the place.

lngnumberObbligatorio

Longitude of the place.

SortOrdertype

The ordering applied to mixed address and place suggestions.

TypeScript
type SortOrder = 'relevance'
  | 'distance';
Stagetype

The current step in the address inference process.

The current step in the address inference process.

  • empty: No input yet.
  • mixed: User is prompted to choose between cities and streets.
  • place: User is selecting a point of interest.
  • street: User is selecting a street.
  • city: User is selecting a city.
  • postcode: User is entering a postcode.
  • street_number: User is entering a street number.
  • street_number_first: Specialized mode where number is entered before street.
  • addition: Selecting a street number addition (e.g., 'A', 'III').
  • direct: Direct address hit (often via postcode).
  • final: A complete, valid address has been identified.
TypeScript
type Stage = 'empty'
  | 'mixed'
  | 'place'
  | 'street'
  | 'city'
  | 'postcode'
  | 'street_number'
  | 'street_number_first'
  | 'addition'
  | 'direct'
  | 'final';