MapsGL Search Control

The MapsGLSearchControl component provides a pre-configured location search interface for MapsGL powered by the Xweather API places (opens in a new tab) and observations (opens in a new tab) endpoints. It composes the base Search component with styling, animations, and interaction behavior optimized for map-based location search.

While the base Search component provides the low-level primitives for building custom search experiences, MapsGLSearchControl assembles them into a production-ready control that handles state management, focus transitions, and responsive layouts automatically.

Features

• Text-based location search with autocomplete
• Support for coordinates (Decimal, DMS), ZIP codes, and airport codes
• Recent selection history
• Grouped results (Places, Stations)
• Integrated Geolocation support
• Smooth transitions and animations
• Customizable result formatting
• Responsive and accessible design

Usage

Below is an example of how MapsGLSearchControl can be used in an interactive way within a tabbed interface.

import { useEffect, useState, useRef } from 'react';
import {
    type SearchResult
    MapsGLSearchControl,
    Tabs,
} from '@xweather/maps-ui-sdk';
 
export default function App() {
    const [currentTab, setCurrentTab] = useState<string | null>(null);
    const searchInputRef = useRef<HTMLInputElement>(null);
    const [coordinates, setCoordinates] = useState<{ lat: number; lon: number } | null>(null);
 
    useEffect(() => {
        if (currentTab === 'search') {
            searchInputRef.current?.focus();
        }
    }, [currentTab]);
 
    const handleSelectResult = (result: SearchResult) => setCoordinates(result.coordinates);
 
    return (
        <Tabs.Provider value={currentTab} onChange={setCurrentTab}>
            <Tabs.List>
                <Tabs.Button value="search">Search Tab</Tabs.Button>
                <Tabs.Button value="settings">Settings Tab</Tabs.Button>
            </Tabs.List>
 
            <Tabs.Content value="search">
                <MapsGLSearchControl
                    className="sm:w-90"
                    inputRef={searchInputRef}
                    onSelectResult={handleSelectResult}
                />
            </Tabs.Content>
            {/* Settings Tab */}
        </Tabs.Provider>
    );
}

Tip: Use result.coordinates for panning/zooming the map. It is populated for both API-backed results and pure coordinate searches, even when no place metadata is available.

Customization

While the component provides a complete, styled interface with sensible defaults, you can customize its appearance and behavior through:

• The className prop for container styling
• Custom result formatting via resultFormatter
• Controlled props for query and recentSelections
• Custom group ordering via searchGroups

MapsGL Integration

The control is designed to work seamlessly with the MapsGL SDK:

• Automatically formats location data from the API
• Handles coordinate systems appropriately
• Maintains consistent styling with other MapsGL controls
• Manages loading states during API requests

Related Components

• Search - The base compound component

API Reference

MapsGLSearchControl

The main component that provides a complete search interface for MapsGL.

Search Results

Results are automatically grouped into three categories:

1. Recent – Previously selected locations.
2. Places – Cities, population centers, and other place-based results.
3. Stations – Observation and reporting stations.

Each group is only displayed if it contains results, and the order can be customized via the searchGroups prop.