Release 3.1.0

Author: Alfiya Tarasenko

BUILD.md

@@ -5,7 +5,7 @@ Use this guide to set up a local workstation and verify changes before publishin
 
 ## 1. Prerequisites
 
-- Node.js 18+ and npm 10+
+- Node.js 20.19+ or 22.12+ and npm 10+
 - For the documentation site: Python 3.9+ with `pip`
 
 ## 2. Install Dependencies
@@ -14,7 +14,7 @@ Use this guide to set up a local workstation and verify changes before publishin
 npm install
 ```
 
-This installs all workspace packages, including the demo app dependencies.
+This installs the library dependencies. The demo app has its own dependency tree under `example/`.
 
 ## 3. Build the Library
 
@@ -28,8 +28,10 @@ npm run build
 
 ## 4. Run Quality Gates
 
-- **Unit tests:** `npm run test`
-- **Linting:** `npm run lint`
+- **Complete test pipeline:** `npm test`
+- **Unit tests only:** `npm run test:unit`
+- **Linting only:** `npm run test:lint`
+- **Build only:** `npm run build`
 
 These should be clean before submitting changes or publishing.
 
@@ -50,7 +52,7 @@ The demo showcases three interactive examples:
    npm install
    npm start      # serves the demo on http://localhost:3000
    ```
-3. The demo watches both the library and app; rebuilding the library will refresh the demo automatically.
+3. The demo links to the library in the parent directory. After changing the library source, run `npm run build` from the repository root; Vite will then reload the linked output.
 
 ## 6. Preview / Build the Documentation Site
 

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geoapify GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -25,7 +25,7 @@ It provides an easy-to-use React wrapper for the [Geoapify Geocoding Autocomplet
 * Customizable design: easily style or theme your component.
 * Accessible with keyboard navigation and ARIA support.
 * Rich results including coordinates, structured address, and metadata.
-* Compatible with React 18–19.
+* Compatible with React 19.
 
 ## Quick Start
 
@@ -69,7 +69,7 @@ Wrap your component with the `GeoapifyContext` and provide your API key:
 </GeoapifyContext>
 ```
 
-Tip: Store your API key in an environment variable and reference it as `process.env.REACT_APP_GEOAPIFY_KEY` for better maintainability.
+Tip: Store your API key in your framework's client-side environment configuration (for example, `import.meta.env.VITE_GEOAPIFY_KEY` in Vite). Client-side API keys are visible in the browser, so configure suitable key restrictions in your Geoapify project.
 
 ### 4. Use the component
 
@@ -110,7 +110,7 @@ const onSuggestionsChange = (list) => {
 | 1.2.x – 1.3.x                         | >= 17.0.0            |
 | 1.4.x – 1.5.x                         | >= 18.0.0            |
 | 2.0.x – 2.2.x                         | >= 18.0.0, <= 19.x.x |
-| 3.0.x                                 | >= 19.0.0, <= 19.x.x |
+| 3.0.x – 3.1.x                         | >= 19.0.0, <= 19.x.x |
 
 > If you prefer to use the library directly without React bindings, check the **[Standalone Usage](https://geoapify.github.io/react-geocoder-autocomplete/standalone-usage/)** section.
 
@@ -133,7 +133,7 @@ The component includes many options for configuration and customization. Below a
 | Property              | Direction | Description                                                                       |
 | --------------------- | --------- | --------------------------------------------------------------------------------- |
 | `placeholder`         | Prop      | Sets the placeholder text for the input field.                                    |
-| `type`                | Prop      | Defines the type of location to search for — e.g. `city`, `street`, or `amenity`. |
+| `type`                | Prop      | Defines the type of location to search for — e.g. `city`, `locality`, `street`, or `amenity`. |
 | `lang`                | Prop      | Sets the language of suggestions and results.                                     |
 | `limit`               | Prop      | Limits the number of suggestions displayed.                                       |
 | `debounceDelay`       | Prop      | Adds a short delay before sending requests, improving performance.                |
@@ -279,7 +279,9 @@ Adds boundary or geometry data (where available) to the selected feature.
   <GeoapifyGeocoderAutocomplete
     addCategorySearch={true}
     showPlacesByCategoryList={true}
-    placesByCategoryFilter={{ categories: ['cafe', 'restaurant'] }}
+    placesByCategoryFilter={{
+      circle: { lon: 13.405, lat: 52.52, radiusMeters: 5000 }
+    }}
     onPlaceByCategorySelect={onPoiSelected}
   />
 </GeoapifyContext>
@@ -291,7 +293,7 @@ const onPoiSelected = ({ place, index }) => {
 };
 ```
 
-Enables category-based search for nearby Points of Interest (POIs) below the input field, filtered by category.
+Enables category-based search and displays nearby Points of Interest (POIs) below the input. The circle filter restricts results to five kilometers around central Berlin.
 
 **Used properties:**
 `addCategorySearch`, `showPlacesByCategoryList`, `placesByCategoryFilter`, `onPlaceByCategorySelect`
@@ -345,7 +347,7 @@ const onClear = (item) => {
 ```tsx
 <GeoapifyContext apiKey="YOUR_API_KEY">
   <GeoapifyGeocoderAutocomplete
-    filterByCountryCode={['DE']}
+    filterByCountryCode={['de']}
     biasByProximity={{ lon: 13.405, lat: 52.52 }}
     addDetails={true}
     placeSelect={onPlaceSelected}

docs-site/docs/api-reference.md

@@ -8,7 +8,7 @@ The React Geocoder Autocomplete component exposes several **props** and **callba
 | ----------------------------- | ---------------------------------------------------- | --------- | ---------------------------------------------------------------- |
 | `value`                       | `string`                                             | Prop      | Current value of the input field.                                |
 | `placeholder`                 | `string`                                             | Prop      | Text shown when the input is empty.                              |
-| `type`                        | `LocationType`                                       | Prop      | Type of place to search for (`country`, `city`, `street`, etc.). |
+| `type`                        | `LocationType`                                       | Prop      | Type of place to search for (`country`, `state`, `city`, `locality`, `postcode`, `street`, or `amenity`). |
 | `lang`                        | `SupportedLanguage`                                  | Prop      | Language of suggestions and results.                             |
 | `limit`                       | `number`                                             | Prop      | Max number of suggestions to show.                               |
 | `debounceDelay`               | `number`                                             | Prop      | Delay (ms) before sending requests after typing.                 |
@@ -20,6 +20,8 @@ The React Geocoder Autocomplete component exposes several **props** and **callba
 | `biasByCountryCode`           | `ByCountryCodeOptions`                               | Prop      | Prioritize results from certain countries.                       |
 | `biasByCircle`                | `ByCircleOptions`                                    | Prop      | Bias results within a circle.                                    |
 | `biasByRect`                  | `ByRectOptions`                                      | Prop      | Bias results within a rectangle.                                 |
+| `position`                    | `GeoPosition`                                        | Prop      | Deprecated alias for `biasByProximity`.                          |
+| `countryCodes`                | `CountyCode[]`                                       | Prop      | Deprecated alias for `filterByCountryCode`.                      |
 | `skipIcons`                   | `boolean`                                            | Prop      | Hide icons in the suggestions list.                              |
 | `addDetails`                  | `boolean`                                            | Prop      | Include detailed place info in results.                          |
 | `allowNonVerifiedHouseNumber` | `boolean`                                            | Prop      | Allow house numbers not verified in data.                        |
@@ -30,8 +32,8 @@ The React Geocoder Autocomplete component exposes several **props** and **callba
 | `hidePlacesByCategoryListAfterSelect`   | `boolean`                                            | Prop      | Hide POI list after selection.                                   |
 | `enablePlacesByCategoryLazyLoading`     | `boolean`                                            | Prop      | Load additional POI items dynamically.                           |
 | `placesByCategoryLimit`                 | `number`                                             | Prop      | Max number of POIs to display.                                   |
-| `placesByCategoryFilter`                | `object`                                             | Prop      | Filters for category-based search.                               |
-| `placesByCategoryBias`                  | `object`                                             | Prop      | Bias rules for category-based search.                            |
+| `placesByCategoryFilter`                | `Record<string, ByCircleOptions \| ByRectOptions \| string>` | Prop | Geographic filters for category-based search. |
+| `placesByCategoryBias`                  | `Record<string, ByCircleOptions \| ByRectOptions \| ByProximityOptions>` | Prop | Geographic bias rules for category-based search. |
 | `preprocessHook`              | `(value: string) => string`                          | Prop      | Modify input before request.                                     |
 | `postprocessHook`             | `(feature: any) => string`                           | Prop      | Modify selected result before display.                           |
 | `suggestionsFilter`           | `(features: any[]) => any[]`                         | Prop      | Filter suggestions before display.                               |
@@ -98,7 +100,7 @@ const placeholderText = 'Search for a location';
 ### `type` (Prop)
 
 **Type:** `LocationType`
-**Description:** Defines the type of place to search for — such as `'country'`, `'city'`, `'postcode'`, `'street'`, or `'amenity'`.
+**Description:** Defines the type of place to search for: `'country'`, `'state'`, `'city'`, `'locality'`, `'postcode'`, `'street'`, or `'amenity'`.
 
 **Example:**
 
@@ -181,7 +183,7 @@ const debounceTime = 400;
 ```
 
 ```jsx
-const allowedCountries = ['US', 'CA']; // Only show addresses in the US and Canada
+const allowedCountries = ['us', 'ca']; // Only show addresses in the US and Canada
 ```
 
 
@@ -279,7 +281,7 @@ const userLocation = { lon: -73.935242, lat: 40.73061 };
 ```
 
 ```jsx
-const preferredCountries = ['US'];
+const preferredCountries = ['us'];
 ```
 
 
@@ -327,6 +329,26 @@ const preferredRegion = {
 };
 ```
 
+### `position` (Deprecated Prop)
+
+**Type:** `GeoPosition`
+**Description:** Deprecated alias for `biasByProximity`. Use `biasByProximity` in new code.
+
+```jsx
+<GeoapifyGeocoderAutocomplete
+  biasByProximity={{ lon: -73.935242, lat: 40.73061 }}
+/>
+```
+
+### `countryCodes` (Deprecated Prop)
+
+**Type:** `CountyCode[]`
+**Description:** Deprecated alias for `filterByCountryCode`. Use `filterByCountryCode` in new code.
+
+```jsx
+<GeoapifyGeocoderAutocomplete filterByCountryCode={['us', 'ca']} />
+```
+
 ### `skipIcons` (Prop)
 
 **Type:** `boolean`
@@ -483,8 +505,8 @@ const maxPlaces = 10;
 
 ### `placesByCategoryFilter` (Prop)
 
-**Type:** `object`
-**Description:** Defines filters for category-based searches, such as location or category constraints.
+**Type:** `Record<string, ByCircleOptions | ByRectOptions | string>`
+**Description:** Defines geographic filters for category-based searches. Supported keys are `circle`, `rect`, `place`, and `geometry`.
 
 **Example:**
 
@@ -499,13 +521,13 @@ const maxPlaces = 10;
 
 ```jsx
 const placesByCategoryFilter = {
-  filter: { circle: { lon: -73.935242, lat: 40.73061, radiusMeters: 5000 } }
+  circle: { lon: -73.935242, lat: 40.73061, radiusMeters: 5000 }
 };
 ```
 
 ### `placesByCategoryBias` (Prop)
 
-**Type:** `object`
+**Type:** `Record<string, ByCircleOptions | ByRectOptions | ByProximityOptions>`
 **Description:** Adds bias rules for category-based search, prioritizing results in certain areas.
 
 **Example:**
@@ -521,7 +543,7 @@ const placesByCategoryFilter = {
 
 ```jsx
 const placesByCategoryBias = {
-  bias: { proximity: { lon: -73.935242, lat: 40.73061 } }
+  proximity: { lon: -73.935242, lat: 40.73061 }
 };
 ```
 

docs-site/docs/index.md

@@ -27,7 +27,7 @@ It's designed to offer a fast, accessible, and customizable autocomplete experie
 
 * **Rich structured output** – Emits detailed selection events containing coordinates, formatted addresses, and Geoapify metadata that can be directly used in your app logic.
 
-* **React compatibility** – Works with React 18 and newer versions. The recommended setup is **React 18+** for the best performance and API alignment.
+* **React compatibility** – Version 3.x supports React 19. See the compatibility table in the project README when using an earlier React release.
 
 ## Learn More
 
@@ -38,4 +38,3 @@ It's designed to offer a fast, accessible, and customizable autocomplete experie
 - [Geoapify Geocoding API documentation](https://apidocs.geoapify.com/docs/geocoding/)
 - [GitHub repository](https://github.com/geoapify/react-geocoder-autocomplete)
 - [Geoapify Developer Portal](https://www.geoapify.com/)
-

docs-site/docs/quick-start.md

@@ -21,12 +21,18 @@ To use the component, you need a **Geoapify API key**.
 1. Sign up at [myprojects.geoapify.com](https://myprojects.geoapify.com/) and create a project.
 2. Copy your API key from the project dashboard.
 3. Start with the **Free plan** (5 requests/sec) and upgrade as needed.
-4. Store the key securely — for example, in an `.env` file:
+4. Store the key in your framework's client-side environment configuration. For example, with Vite:
 
 ```bash
-REACT_APP_GEOAPIFY_KEY=YOUR_API_KEY
+VITE_GEOAPIFY_KEY=YOUR_API_KEY
 ```
 
+```jsx
+const apiKey = import.meta.env.VITE_GEOAPIFY_KEY;
+```
+
+Client-side API keys are visible in the browser, so configure suitable key restrictions in your Geoapify project.
+
 ## Integrating the Component into Your React Project
 
 ### 1. Importing Styles
@@ -142,4 +148,3 @@ Now that you've added the component and verified it works, you can:
    * [Geocoding API](https://apidocs.geoapify.com/docs/geocoding)
    * [Places API](https://apidocs.geoapify.com/docs/places)
    * [Geoapify Playground](https://apidocs.geoapify.com/playground/geocoding)
-

example/README.md

@@ -1,5 +1,28 @@
-This example was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).
+# React Geocoder Autocomplete Example
 
-It is linked to the react-geocoder-autocomplete package in the parent directory for development purposes.
+This Vite application demonstrates the local `@geoapify/react-geocoder-autocomplete` package from the parent directory.
 
-You can run `npm install` and then `npm start` to test your package.
+## Run locally
+
+1. Replace the demo key in `src/config.js` with your Geoapify API key.
+2. Install and start the example:
+
+   ```bash
+   npm install
+   npm start
+   ```
+
+3. Open [http://localhost:3000](http://localhost:3000).
+
+The example links React, React DOM, and the component library from the repository root. After changing the library source, rebuild it from the root:
+
+```bash
+npm run build
+```
+
+## Production build
+
+```bash
+npm run build
+npm run preview
+```

example/index.html

@@ -14,7 +14,6 @@
   <body>
     <noscript>You need to enable JavaScript to run this app.</noscript>
     <div id="root"></div>
-    <script type="module" src="/src/index.js"></script>
+    <script type="module" src="/src/index.jsx"></script>
   </body>
 </html>
-