@placekit/autocomplete-react

PlaceKit Autocomplete React Library

All-in-one autocomplete experience for your React web apps

Quick start • Component properties • Custom hook • Documentation • License

---

PlaceKit Autocomplete React Library is a React wrapper of PlaceKit Autocomplete JS. It features a compoment ready to use, and a custom hook for custom implementations. It also is TypeScript compatible.

🎯 Quick start

First, install PlaceKit Autocomplete React using npm package manager:

npm install --save @placekit/autocomplete-react

Then import the package and perform your first address search:

import { PlaceKit } from '@placekit/autocomplete-react';

const MyComponent = (props) => {
  return (
    <PlaceKit apiKey="<your-api-key>" />
  );
};

export default MyComponent;

Also, import default style from @placekit/autocomplete-js/dist/placekit-autocomplete.css (@placekit/autocomplete-js is set as a dependency of this package and will automatically be installed). It will style the suggestions list and the input. If you have trouble importing CSS from node_modules, copy/paste its content into your own CSS.

⚙️ Component properties

<PlaceKit
  apiKey="<your-api-key>"
  useGeolocation={false} // hide "ask geolocation" button
  className="your-custom-classes" // <div> wrapper custom classes

  // PlaceKit Autocomplete JS options
  options={{
    offset: 4,
    template: (item, index) => {},
    formatValue: (item) => {},
    timeout: 5000,
    maxResults: 5,
    types: ['city'],
    language: 'fr',
    countries: ['fr'],
    coordinates: '48.86,2.29',
  }}

  // handlers
  onOpen={() => {}}
  onClose={() => {}}
  onResults={(query, results) => {}}
  onPick={(value, item, index) => {}}
  onError={(error) => {}}
  onFreeForm={(isFreeForm) => {}}
  onGeolocation={(hasGeolocation, position) => {}}

  // and any other property will be forwared to the <input> element
  id="my-input"
  name="address"
  placeholder="Search places..."
  disabled={true}
/>

Please refer to PlaceKit Autocomplete JS documentation for more details about the options.

A few additional notes:

• The <input> is using React ref attribute. It is therefore an uncontrolled component and should be treated as such.
• If you want to customize the input style, create your own component using our custom hook. You can reuse our component as a base.
• If you want to customize the suggestions list style, don't import our stylesheet and create your own following PlaceKit Autocomplete JS documentation.
• Handlers are exposed directly as properties for ease of access.

🪝 Custom hook

If our component doesn't suit your needs, you can build your own using the provided custom hook usePlaceKit():

import { usePlaceKit } from '@placekit/autocomplete-react';

const MyComponent = (props) => {
  const { target, client, isFreeForm, hasGeolocation } = usePlaceKit('<your-api-key>', {});

  return (
    <input ref={target} />
  );
};

Please refer to PlaceKit Autocomplete JS documentation for more details about the options.

A few additional notes:

• target is a React ref object.
• The handlers can be passed through options.handlers, but also be set with client.on() (better use a useState() in that case).
• Don't pass a destructured object into usePlaceKit second argument (options), this will cause an infinite update loop as a destructured object will constantly be a fresh new value by nature.
• isFreeForm and hasGeolocation are separately set inside the hook, as client.isFreeForm and client.hasGeolocation are stateless.

⚠️ NOTE: you are not allowed to hide the PlaceKit logo unless we've delivered a special authorization. To request one, please contact us using our contact form

⚖️ License

PlaceKit Autocomplete React Library is an open-sourced software licensed under the MIT license.