@ouigoo/location-picker

A universal JavaScript library for location selection, compatible with React and Vanilla JS.

🚀 Features

• ✅ Google Maps: Full integration via Google Maps API
• ✅ Geocoding: Address ↔ coordinates conversion
• ✅ Geolocation: "My location" button
• ✅ Satellite view: Map/satellite toggle
• ✅ Search: Address search
• ✅ Responsive: Mobile-first design
• ✅ Themes: Customizable (ouigoo, dark, etc.)
• ✅ Accessible: Keyboard and screen reader support

📦 Installation

npm install @ouigoo/location-picker

🎯 Usage

React

import { OuigooLocationPicker } from '@ouigoo/location-picker/react';

function App() {
  const handleLocationSelect = (result) => {
    console.log('Selected location:', result);
    // result = {
    //   location: { lat: 6.129, lng: 1.215 },
    //   address: "5736+MGW, Rue Hodjeme, Lomé, Togo",
    //   name: "AMINOU-NÔ",
    //   city: "Lomé",
    //   state: "Région maritime",
    //   country: "TG",
    //   timestamp: "2024-01-15T10:30:00.000Z"
    // }
  };

  return (
    <OuigooLocationPicker
      apiKey="your-google-maps-api-key"
      onLocationSelect={handleLocationSelect}
      centerOnUserLocation={true}
      theme="ouigoo"
    />
  );
}

Vanilla JS

<div id="location-picker"></div>

<script src="./dist/vanilla.js"></script> 
<script>
  // Initialization
  OuigooLocationPicker.createLocationPicker({
    container: '#location-picker',
    apiKey: 'your-google-maps-api-key',
    centerOnUserLocation: true,
    onLocationSelect: function(result) {
      console.log('Selected location:', result);
      // result contains: location, address, name, city, state, country, timestamp
    }
  }).then(function(picker) {
    console.log('LocationPicker initialized');
  });
</script>

⚙️ Configuration

Main Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | container | string|HTMLElement | - | (Required) CSS selector or DOM element for the container. | | apiKey | string | '' | (Required) Google Maps API key. | | defaultCenter | {lat, lng} | { lat: 6.29, lng: 1.79 } | Default map center (Benin/Togo). | | defaultZoom | number | 8.28 | Default map zoom level. | | locationZoom | number | 17 | Zoom level applied after selecting a location. | | language | string | 'fr' | Interface and Google Maps results language. | | theme | string | 'ouigoo' | Visual theme ('ouigoo', 'dark', or a custom class name). | | enableSatelliteView | boolean | true | Enable satellite view button. | | enableMyLocation | boolean | true | Enable geolocation button. | | enableSearch | boolean | true | Enable address search bar. | | country | string | null | Country code (e.g., 'TG') to center the map initially. | | centerOnUserLocation | boolean | false | If true, attempts to center the map on the user's location at startup. | | confirmButtonStyle | string | 'rectangle' | Confirmation button style ('rectangle' or 'circular'). | | allowedCountries | string[] | ['TG', 'BJ', ...] | List of country codes to restrict search. |

Callbacks

| Callback | Parameters | Description | |----------|------------|-------------| | onLocationSelect | (result) | Location confirmed by the user. See Result Structure | | onAddressChange | (address) | Address updated (displayed in the interface) | | onLoadingChange | (isLoading) | Loading state | | onError | (error) | Error occurred |

Result Structure

When the user confirms a location, the returned result object contains the following properties:

{
  location: {
    lat: 6.129654,      // Latitude
    lng: 1.215964       // Longitude
  },
  address: "5736+MGW, Rue Hodjeme, Lomé, Togo",  // Full formatted address
  name: "AMINOU-NÔ",                              // Place name (if available)
  city: "Lomé",                                   // City
  state: "Région maritime",                       // State/Region
  country: "TG",                                  // Country code (ISO 3166-1 alpha-2)
  timestamp: "2024-01-15T10:30:00.000Z"          // Confirmation date/time (ISO 8601)
}

Important notes:

• The name field contains the place name when selected via autocomplete or available in geocoding data
• If the name is not available, name will be an empty string ""
• The city and state fields may be empty if the information is not available
• The country field contains the 2-letter country code (e.g., "TG" for Togo, "BJ" for Benin)
• The interface preferentially displays the name if available, otherwise the address

🎨 Themes

Ouigoo Theme (default)

.ouigoo-location-picker.ouigoo {
  --primary-color: #ff6600;
  --background-color: #ffffff;
}

Dark Theme

<LocationPicker theme="dark" />

Custom Theme

.ouigoo-location-picker.custom {
  --primary-color: #your-color;
  --background-color: #your-bg;
}

🔧 Advanced API

React Hook

import { useLocationPicker } from '@ouigoo/location-picker/react';

function MyComponent() {
  const {
    picker,
    isReady,
    createPicker,
    setLocation,
    getCurrentLocation,
    searchLocation
  } = useLocationPicker();

  useEffect(() => {
    createPicker({
      container: '#my-picker',
      apiKey: 'your-key'
    });
  }, []);

  const handleSearch = () => {
    searchLocation('Paris, France');
  };

  return (
    <div>
      <div id="my-picker" />
      <button onClick={handleSearch}>Search Paris</button>
    </div>
  );
}

Programmatic Control (Vanilla)

const picker = await OuigooLocationPicker.createLocationPicker({
  container: '#picker',
  apiKey: 'your-key'
});

// Set a location
picker.setLocation({ lat: 48.8566, lng: 2.3522 });

// Search
await picker.searchLocation('Cotonou');

// Get current position
picker.getCurrentLocation();

// Destroy instance
picker.destroy();

📱 Responsive Design

The library is mobile-first and adapts automatically:

• Desktop: Full interface with all controls
• Tablet: Touch-optimized interface
• Mobile: Simplified interface, touch controls

♿ Accessibility

• Full keyboard support
• Screen reader compatible
• Respected contrasts (WCAG 2.1)
• Visible focus on all elements

🏗️ Build

npm run build

Generates:

• dist/vanilla.js - Vanilla UMD version
• dist/vanilla.esm.js - Vanilla ES modules version
• dist/react.js - React UMD version
• dist/react.esm.js - React ES modules version

📄 License

MIT © Ouigoo Team

🤝 Contributing

1. Fork the project
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📞 Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues