Maps UI SDK - Data Viewer

The DataViewer uses the compound component pattern and consists of several subcomponents for building flexible data viewing interfaces.

Features

• Integrated Data Fetching: Built-in integration with the Weather API through WeatherApiDataFetcher
• Loading States: Automatic handling of loading states through DataViewer.Card and DataViewer.LoadingFallback
• Flexible Layout: Compound components for header, banner, and scrollable body sections
• Card System: Pre-built card components with consistent styling and data validation
• Built-in Views: Ready-to-use view components for common weather data displays

WeatherApiDataFetcher

The WeatherApiDataFetcher component wraps the DataProvider and the useWeatherApi hook which integrates with the Xweather Weather API.

Once data is returned from the useWeatherApi hook it is passed to the DataProvider, which makes the data accessible to components further down the component hierarchy. In the example below, the WeatherApiDataFetcher is being used directly in the banner because the card styles are not needed there. The card components inside <DataViewer.Body> wrap WeatherApiDataFetcher, DataViewer.Card, and a view component such as ImpactsView. This makes it very simple to add built-in views with consistent card styling to the DataViewer, but if you want to customize the design you can also build your own views with the helper components.

Built-in View components

A series of data viewer cards are already set up and configured for you for basic weather information, like conditions, forecasts, and threats. The following views can be used within your own data viewer configurations:

The prebuilt views cover some of the most common weather data representations, allowing you to quickly integrate comprehensive weather information into your application. By leveraging WeatherApiDataFetcher and DataViewer.Card, which encapsulate the data fetching and card structure, you can greatly simplify the process of creating your own tailored data representations relevant to your use case.

Forecast

ForecastCard follows the same pattern as the other built-in cards: it combines the forecast API requests, the card wrapper, and the default forecast UI into a single component.

Forecast is also available as a compound component API for cases that need more control. You can configure ForecastCard with props such as intervals, metrics, and paramsByEndpoint, or build custom forecast layouts with Forecast.View, Forecast.Table, Forecast.IntervalSelector, Forecast.MetricSelector, and Forecast.Outlook.

By default, ForecastCard renders the built-in forecast view using the daily and 3-hour interval presets.

When only one interval is configured, Forecast.IntervalSelector isn’t rendered.

Forecast examples

Default forecast usage:

<ForecastCard />

Replacing the deprecated daily and hourly forecast cards:

<ForecastCard 
  intervals={[FORECAST_INTERVAL_PRESETS.oneDay]} 
  includeOutlook={false}
/>
 
<ForecastCard
  intervals={[FORECAST_INTERVAL_PRESETS.threeHour]}
  includeOutlook={false}
/>

Customizing the built-in forecast layout while keeping the card and fetch integration:

<ForecastCard
  intervals={[
    FORECAST_INTERVAL_PRESETS.oneDay,
    FORECAST_INTERVAL_PRESETS.threeHour
  ]}
  defaultDataView="wind"
>
  <Forecast.View
    outlook={null}
    table={<Forecast.Table renderPrecipChance={null} />}
  />
</ForecastCard>

Building a custom forecast layout with the Forecast compound components:

<ForecastCard
  intervals={[
    FORECAST_INTERVAL_PRESETS.oneDay,
    FORECAST_INTERVAL_PRESETS.threeHour
  ]}
>
  <Forecast.Outlook />
  <Forecast.IntervalSelector />
  <Forecast.MetricSelector />
  <Forecast.Table />
</ForecastCard>

Usage

Integration with LocationProvider

The DataViewer is typically used with a LocationProvider to automatically fetch and display location-specific weather data:

const LocalWeatherViewer = () => {
  const { coordinatesString } = useLocationContext();
 
  if (!coordinatesString) {
    return null;
  }
 
  return (
    <DataViewer>
      <DataViewer.Header>
        <DataViewer.Title>Local Weather</DataViewer.Title>
        <DataViewer.CloseButton />
      </DataViewer.Header>
      <DataViewer.Banner>
        <WeatherApiDataFetcher
          endpoint="places"
          params={{
            p: coordinatesString
          }}
        >
          <PlacesView />
        </WeatherApiDataFetcher>
      </DataViewer.Banner>
      <DataViewer.Body>
        <AlertsCard />
        <ThreatsCard />
        <ImpactsCard />
        <ConditionsCard />
        <ForecastCard />
      </DataViewer.Body>
    </DataViewer>
  );
};
 
<LocationProvider>
  <LocalWeatherViewer />
</LocationProvider>

Custom Card Component

You can create reusable card components following the same pattern as the built-in cards:

interface CustomWeatherCardProps {
    className?: string;
    params?: Record<string, string>;
    title?: string;
    children?: ReactNode;
    dataValidator?: (data: any) => boolean;
}
 
export const CustomWeatherCard = ({
    className,
    title = 'Custom Weather Data',
    params = {},
    children = <CustomWeatherView />,
    dataValidator = (data: any) => !isEmpty(data)
}: CustomWeatherCardProps) => {
    const { coordinatesString } = useLocationContext();
 
    return (
        <WeatherApiDataFetcher
            endpoint="conditions"
            params={{
                p: coordinatesString,
                fields: 'tempF,tempC,humidity,windSpeedMPH,windSpeedKPH',
                ...params
            }}>
            <DataViewer.Card
                className={className}
                dataValidator={dataValidator}>
                <DataViewer.CardDivider />
                {title && <DataViewer.CardTitle>{title}</DataViewer.CardTitle>}
                <DataViewer.CardBody>
                    {children}
                </DataViewer.CardBody>
            </DataViewer.Card>
        </WeatherApiDataFetcher>
    );
};

Custom View Component

Create a view component that consumes the data from the DataContext:

const CustomWeatherView = () => {
  const { data } = useDataContext();
 
  return (
    <div>
      <p>Temperature: {data.tempF}°F ({data.tempC}°C)</p>
      <p>Humidity: {data.humidity}%</p>
      <p>Wind Speed: {data.windSpeedMPH} mph ({data.windSpeedKPH} kph)</p>
    </div>
  );
};

This pattern allows you to:

• Create reusable card components with consistent styling
• Handle loading states automatically through DataViewer.Card
• Validate data before rendering
• Customize the view while maintaining the card structure

API Reference

DataViewer (Root)

The base wrapper component that provides the modal functionality.

DataViewer.Header

Header section of the data viewer.

DataViewer.Banner

A container that can be used for displaying fixed content above the main body.

DataViewer.Body

The main content area of the data viewer with support for scrolling.

DataViewer.Card

A card container for displaying data sections with built-in loading states and data validation.

DataViewer.CardBody

Container for card content.

DataViewer.CardTitle

Styled heading for cards.

DataViewer.DataWrapper

Utility component for handling data loading states.