barikoi-map-widget

📚 Barikoi Map Widget Documentation

The Barikoi Map Widget simplifies the integration of autocomplete and map functionalities into your web application. It provides seamless connectivity between the autocomplete input and the map display, eliminating the need for separate handling. This widget is particularly useful for applications that require geolocation features, such as finding places or visualizing locations on a map.

📦 Installation

To install the barikoi-map-widget library, run:

npm install barikoi-map-widget

🛠️ Usage

Wrap your components with the BarikoiMapProvider to provide the necessary context for the widget:

import React from 'react';
import { BarikoiMapProvider } from 'barikoi-map-widget';
import BarikoiAutocompleteComponent from './BarikoiAutoCompleteComponent';
import BarikoiMapComponent from './BarikoiMapComponent';

const App = () => {
  return (
    <BarikoiMapProvider>
      <BarikoiAutocompleteComponent />
      <BarikoiMapComponent />
    </BarikoiMapProvider>
  );
};

export default App;

🔍 BarikoiAutoComplete

The BarikoiAutoComplete component is a customizable search input field with real-time autocomplete suggestions fetched from the Barikoi API. It supports debounced search, smooth dropdown animations, and allows custom styling via className props.

Basic Example

import { BarikoiAutocomplete } from 'barikoi-map-widget';

const BarikoiAutocompleteComponent = () => {
  return (
    <div>
      <h1>Search</h1>
      <BarikoiAutocomplete
        apiKey="YOUR_BARIKOI_API_KEY"
        className={{
          container: 'custom-container',
          input: 'custom-input',
          dropdown: 'custom-dropdown',
          dropdownItem: 'custom-dropdown-item',
          noResult: 'custom-no-result',
        }}
      />
    </div>
  );
};
export default BarikoiAutocompleteComponent;

📋 Props

Prop Name	Type	Required	Description
apiKey	string	✅ Yes	Your Barikoi API key for fetching autocomplete suggestions.
className	object	❌ No	Object to override default styles using CSS class names.

Class Name Object Structure

Key	Type	Description
container	string	Class for the main container.
input	string	Class for the input field.
dropdown	string	Class for the dropdown container.
dropdownVisible	string	Class for the dropdown visibility.
dropdownItem	string	Class for each dropdown item.
noResult	string	Class for "No Results Found" message.
clearButton	string	Class for clear button.

🎨 Styling

The component uses default inline styles but allows className overrides. Below is an example of CSS customizations:

/* customStyles.css */
.custom-container {
  border: 2px solid blue;
  border-radius: 6px;
}

.custom-input {
  font-size: 16px;
  border: 1px solid #aaa;
}

.custom-dropdown {
  border: 1px solid green;
  background-color: #f9fafb;
}

.custom-dropdown-item {
  padding: 12px;
  font-weight: bold;
}

.custom-no-result {
  color: red;
  font-style: italic;
}

📊 State Management

The BarikoiAutoComplete component uses the following state variables to manage its internal state:

• searchedPlace: Tracks the current search input value.
• setSearchedPlace: A function to update the searchedPlace state.
• selectedPlace: Stores the place that the user has selected from the autocomplete suggestions.
• setSelectedPlace: A function to update the selectedPlace state.
• suggestions: Contains the list of autocomplete suggestions fetched from the API.
• setSuggestions: A function to update the suggestions state.
• isAutocompleteLoading: A boolean that indicates whether the autocomplete data is being fetched.
• setIsAutocompleteLoading: A function to update the isAutocompleteLoading state.

🗺️ BarikoiMap

The BarikoiMap component is a customizable React component designed to render a map using the Barikoi Maps service. It provides several map controls, such as geolocation, fullscreen mode, and scale controls, and allows for dynamic positioning of a marker. The map’s initial view state and style are customizable, and the component provides an API key to integrate with Barikoi’s map services.

Basic Example

import { BarikoiMap } from 'barikoi-map-widget';

const BarikoiMapComponent = () => {
  const BARIKOI_API_KEY = 'YOUR_BARIKOI_API_KEY'; // Replace with your actual API key
  const initialViewState = {
    longitude: 90.36402,
    latitude: 23.823731,
    minZoom: 4,
    maxZoom: 30,
    zoom: 16,
  };
  return (
    <BarikoiMap
      apiKey={BARIKOI_API_KEY}
      initialViewState={initialViewState}
      controls={{
        marker: {
          enabled: true,
        },
        fullscreen: {
          enabled: true,
          position: 'top-left',
        },
        geolocate: {
          enabled: true,
          position: 'bottom-right',
        },
      }}
      mapStyle="osm-liberty" // Change to desired style like 'barikoi-dark'
      className={{
        container: 'map-container',
      }}
    />
  );
};
export default BarikoiMapComponent;

CSS

.map-container {
  width: 100%;
  height: 100vh;
}

You need to add this to see the map. Please change the style as your project requires.

📋 Props

Prop Name	Type	Required	Description
apiKey	string	✅ Yes	Your Barikoi API key for fetching autocomplete suggestions.
initialViewState	object	❌ No	An object defining the initial map view state. Includes properties like longitude, latitude, minZoom, maxZoom, zoom.
controls	object	❌ No	A configuration object to enable/disable various map controls.
mapStyle	string	❌ No	The map style to be applied, passed as a string. Example: osm-liberty, osm-bright, barikoi-dark.
className	string	✅ Yes	Additional class names to apply to the component's container.

Control Prop Structure:

const controls = {
  geolocate: { enabled: true, position: 'top-left' },
  fullscreen: { enabled: true, position: 'top-right' },
  navigation: { enabled: true, position: 'bottom-left' },
  scale: { enabled: true, position: 'bottom-right' },
  marker: { enabled: true, url: 'path-to-marker-icon' },
};

📊 State Management

The map-related state includes:

• zoomLevel: The zoom level of the map..
• setZoomLevel: A setter function to update the zoom level.
• centerPoint: The geographical coordinates of the center point. Contains lat (latitude) and lng (longitude).
• setCenterPoint: A setter function to update the center point.

Get Barikoi API key

To access Barikoi's API services, you need to:

1. Register on Barikoi Developer Dashboard.
2. Verify with your phone number.
3. Claim your API key.

Once registered, you'll be able to access the full suite of Barikoi API services. If you exceed the free usage limits, you'll need to subscribe to a paid plan.

Learning Resources

• Barikoi API Documentation

License

This library is licensed under the MIT License. See the LICENSE file for details.

Support

For any issues or questions, please contact [e-mail].