Xweather Maps UI SDK

A modular React component library empowering developers to build high-quality, customizable weather mapping interfaces. It combines ready-to-use weather controls, flexible UI components, and utilities to support diverse mapping solutions.

Built on modern React patterns like composable component APIs and context-driven state management, the Maps UI SDK provides complete control over component composition, styling, and behavior while maintaining accessibility best practices. It integrates seamlessly with MapsGL (opens in a new tab) and the Xweather API (opens in a new tab) simplifying the management of weather layers, data views, time-based animations, and location search without sacrificing flexibility.

Get started quickly with our Getting Started guide, or explore the examples to see what's possible.

Key Features

MapsGL Integration – Direct MapsGL integration with both pre-built and fully customizable controls
Xweather API Integration – Built-in data fetching and display through DataViewer and Search components
Modular Component Architecture – Combines high-level provider components for rapid implementation with flexible building blocks for custom UI solutions.
Context-Based State Management – Easily share state between components with React Context providers
Flexible Styling – Minimal styling by default with full control over appearance through className props and data attributes
TypeScript Support – Comprehensive type definitions for excellent IDE integration and type safety
Accessibility-First Design – Components follow WAI-ARIA best practices with keyboard navigation and screen reader support

Core Components

MapsGL Integration

Specialized components and providers tightly coupled with MapsGL for map-specific functionality.

MapsGLMapControllerProvider – Core provider that integrates with the MapsGL Map Controller, providing access to map controller instances throughout your application
MapsGLLayersProvider – State management solution for MapsGL weather layers, handling layer lifecycle, styling, and state synchronization
MapsGLLayersControl – Interface for managing map layer visibility and styling, supporting both individual and grouped layer controls
MapsGLTimelineControl – Specialized timeline interface for time-based map animations with playback controls and time navigation
MapsGLSearchControl – Pre-configured search interface designed for MapsGL integration, with built-in result grouping and location history

UI Building Blocks

Generic, flexible UI components usable independently or combined with MapsGL-specific components.

Timeline – Customizable timeline component for time-based animations with scrubber, tick marks, and playback controls
Search – Location search with autocomplete, keyboard navigation, and customizable result rendering
DataViewer – Modal interface for displaying weather data cards integrated with the Xweather API
Layout Primitives – Positioning utilities (Anchor, Stack etc.), controls (RadioGroup, Select, etc.), animation components (Slide, Fade, etc.), and more for building responsive interfaces

Concepts

The Maps UI SDK is built around several core concepts that enable its flexibility.

Compound Components

The SDK uses the compound component pattern, where related components are grouped together under a parent component namespace:

<Timeline.Provider>
  <Timeline.Container>
    <Timeline.Track>
      <Timeline.Scrubber />
      <Timeline.Ticks>
        {(tick) => <Timeline.Tick tick={tick} />}
      </Timeline.Ticks>
    </Timeline.Track>
    <Timeline.AnimationControl />
  </Timeline.Container>
</Timeline.Provider>

This pattern allows for:

Logical grouping of related components
Implicit state sharing via React Context
Flexible and intuitive composition
Adaptive complexity per use case

Context Providers

The SDK uses React Context to manage and share state between components without the need for extensive prop drilling:

<SettingsProvider>
  <MapsGLMapControllerProvider>
    <MapsGLLayersProvider>
      <MapsGLLayersControl />
      <MapsGLTimelineControl />
    </MapsGLLayersProvider>
  </MapsGLMapControllerProvider>
</SettingsProvider>

These providers:

Create a consistent state management pattern
Enable component communication without props drilling
Provide hooks for accessing shared state
Support nested contexts for complex state requirements while maintaining a clear separation of concerns

Composition Over Configuration

The SDK encourages building complex interfaces through clear, declarative component composition over highly configurable, complex components. This makes customization intuitive and ensures scalability:

<Search>
  <Search.Bar>
    <Search.Input />
    <Search.Clear />
  </Search.Bar>
  <Search.ResultsFetcher>
    <Search.ResultsData>
      {({ hasResults }) => hasResults && (
        <Search.List>
          <Search.Item>
            <Search.ItemButton/>
          </Search.Item>
        </Search.List>
      )}
    </Search.ResultsData>
  </Search.ResultsFetcher>
</Search>

This approach:

Gives you fine-grained control over component structure
Makes customization intuitive through component composition
Enables progressive enhancement of basic components
Supports conditional rendering at any level

What You Can Build

With the Maps UI SDK's modular architecture and deep integration with MapsGL and the Xweather API, you can rapidly create powerful weather mapping solutions tailored to your project’s needs:

Interactive dashboards with dynamic weather layers and custom data views.
Custom map interfaces offering granular layer control and precise styling.
Time-based weather animations featuring intuitive timeline controls and adjustable playback.
Location-aware apps with built-in search functionality.

Getting Started