or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

carto.md core-engine.md effects.md extensions.md index.md json-config.md layers.md map-integration.md react.md views.md widgets.md

tile.json

React Integration

React components and hooks for integrating deck.gl visualizations into React applications, providing declarative API patterns and lifecycle management.

Capabilities

DeckGL Component

Main React component for rendering deck.gl visualizations within React applications.

/**
 * Main React component for deck.gl visualizations
 * Provides declarative API for managing deck.gl instances
 */
const DeckGL: React.ForwardRefExoticComponent<
  DeckGLProps & React.RefAttributes<DeckGLRef>
>;

interface DeckGLProps extends DeckProps {
  /** CSS styles for the container */
  style?: React.CSSProperties;
  /** CSS class name for the container */
  className?: string;
  /** Child elements to render inside the container */
  children?: React.ReactNode;
}

interface DeckGLRef {
  /** Access to underlying Deck instance */
  deck: Deck;
  /** Pick objects at screen coordinates */
  pickObject(opts: PickObjectOptions): PickingInfo | null;
  /** Pick multiple objects at screen coordinates */
  pickMultipleObjects(opts: PickMultipleObjectsOptions): PickingInfo[];
}

Basic Usage:

import React from 'react';
import DeckGL from '@deck.gl/react';
import { ScatterplotLayer, MapView } from 'deck.gl';

function MyMap() {
  const layers = [
    new ScatterplotLayer({
      id: 'scatter',
      data: myData,
      getPosition: d => d.coordinates,
      getRadius: 100,
      getFillColor: [255, 0, 0]
    })
  ];

  return (
    <DeckGL
      initialViewState={{
        longitude: -122.4,
        latitude: 37.8,
        zoom: 10
      }}
      controller={true}
      layers={layers}
      style={{ width: '100%', height: '400px' }}
    />
  );
}

React Integration with Map Libraries

Mapbox GL Integration

import React from 'react';
import DeckGL from '@deck.gl/react';
import { Map } from 'react-map-gl';

function MapboxDeckGL() {
  return (
    <DeckGL
      initialViewState={{
        longitude: -122.4,
        latitude: 37.8,
        zoom: 10
      }}
      controller={true}
      layers={layers}
    >
      <Map
        mapboxAccessToken={MAPBOX_ACCESS_TOKEN}
        mapStyle="mapbox://styles/mapbox/light-v9"
      />
    </DeckGL>
  );
}

Google Maps Integration

import React from 'react';
import { GoogleMapsOverlay } from '@deck.gl/google-maps';
import { ScatterplotLayer } from 'deck.gl';

function GoogleMapsDeckGL() {
  const overlay = new GoogleMapsOverlay({
    layers: [
      new ScatterplotLayer({
        id: 'scatter',
        data: myData,
        getPosition: d => d.coordinates,
        getRadius: 100,
        getFillColor: [255, 0, 0]
      })
    ]
  });

  // Add overlay to Google Maps instance
  overlay.setMap(googleMapInstance);

  return <div id="google-map" style={{ width: '100%', height: '400px' }} />;
}

React Widgets

Pre-built React components for common UI controls.

/**
 * Zoom control widget for React applications
 */
function ZoomWidget(props: ZoomWidgetProps): JSX.Element;

interface ZoomWidgetProps {
  /** Widget ID */
  id?: string;
  /** Widget placement */
  placement?: WidgetPlacement;
  /** Custom style */
  style?: React.CSSProperties;
  /** Custom class name */
  className?: string;
  /** View ID for multi-view setups */
  viewId?: string;
  /** Zoom in label */
  zoomInLabel?: string;
  /** Zoom out label */
  zoomOutLabel?: string;
  /** Transition duration */
  transitionDuration?: number;
}

/**
 * Compass navigation widget for React applications
 */
function CompassWidget(props: CompassWidgetProps): JSX.Element;

interface CompassWidgetProps {
  /** Widget ID */
  id?: string;
  /** Widget placement */
  placement?: WidgetPlacement;
  /** Custom style */
  style?: React.CSSProperties;
  /** Custom class name */
  className?: string;
  /** View ID for multi-view setups */
  viewId?: string;
  /** Transition duration */
  transitionDuration?: number;
}

/**
 * Fullscreen toggle widget for React applications
 */
function FullscreenWidget(props: FullscreenWidgetProps): JSX.Element;

interface FullscreenWidgetProps {
  /** Widget ID */
  id?: string;
  /** Widget placement */
  placement?: WidgetPlacement;
  /** Custom style */
  style?: React.CSSProperties;
  /** Custom class name */
  className?: string;
  /** Enter fullscreen label */
  enterLabel?: string;
  /** Exit fullscreen label */
  exitLabel?: string;
}

type WidgetPlacement = 
  | 'top-left' 
  | 'top-right' 
  | 'bottom-left' 
  | 'bottom-right'
  | 'fill';

React Hooks

/**
 * Hook for managing widget state and interactions
 */
function useWidget<T extends Widget>(
  widget: T,
  viewId?: string
): {
  widget: T;
  viewId: string;
  setViewState: (viewState: ViewState) => void;
};

Context API

interface DeckGLContextValue {
  /** Current deck instance */
  deck?: Deck;
  /** Current view state */
  viewState?: ViewState;
  /** View state setter */
  setViewState?: (viewState: ViewState) => void;
  /** Current viewport */
  viewport?: Viewport;
}

const DeckGLContext: React.Context<DeckGLContextValue>;

Usage Examples

Basic React Component

import React, { useState } from 'react';
import DeckGL from '@deck.gl/react';
import { ScatterplotLayer } from 'deck.gl';

interface DataPoint {
  coordinates: [number, number];
  size: number;
  color: [number, number, number];
}

interface MapComponentProps {
  data: DataPoint[];
}

function MapComponent({ data }: MapComponentProps) {
  const [viewState, setViewState] = useState({
    longitude: -122.4,
    latitude: 37.8,
    zoom: 10,
    bearing: 0,
    pitch: 0
  });

  const layers = [
    new ScatterplotLayer({
      id: 'scatter',
      data,
      getPosition: (d: DataPoint) => d.coordinates,
      getRadius: (d: DataPoint) => d.size,
      getFillColor: (d: DataPoint) => d.color,
      radiusMinPixels: 5,
      radiusMaxPixels: 100,
      pickable: true
    })
  ];

  return (
    <DeckGL
      viewState={viewState}
      onViewStateChange={({viewState}) => setViewState(viewState)}
      controller={true}
      layers={layers}
      style={{ width: '100%', height: '600px' }}
      onHover={(info) => {
        // Handle hover events
        console.log('Hovered:', info.object);
      }}
      onClick={(info) => {
        // Handle click events
        console.log('Clicked:', info.object);
      }}
    />
  );
}

Multi-View React Setup

import React, { useState } from 'react';
import DeckGL from '@deck.gl/react';
import { MapView, OrbitView } from 'deck.gl';

function MultiViewComponent() {
  const [viewState, setViewState] = useState({
    map: {
      longitude: -122.4,
      latitude: 37.8,
      zoom: 10
    },
    orbit: {
      target: [0, 0, 0],
      distance: 100,
      rotationX: 0,
      rotationOrbit: 0,
      zoom: 1
    }
  });

  const views = [
    new MapView({
      id: 'map',
      x: '0%',
      y: '0%',
      width: '50%',
      height: '100%',
      controller: true
    }),
    new OrbitView({
      id: 'orbit', 
      x: '50%',
      y: '0%',
      width: '50%',
      height: '100%',
      controller: true
    })
  ];

  return (
    <DeckGL
      views={views}
      viewState={viewState}
      onViewStateChange={({viewState}) => setViewState(viewState)}
      layers={layers}
      style={{ width: '100%', height: '600px' }}
    />
  );
}

With React Map GL

import React, { useState } from 'react';
import DeckGL from '@deck.gl/react';
import { Map } from 'react-map-gl';
import { ScatterplotLayer } from 'deck.gl';

function MapboxIntegration() {
  const [viewState, setViewState] = useState({
    longitude: -122.4,
    latitude: 37.8,
    zoom: 10,
    bearing: 0,
    pitch: 0
  });

  const layers = [
    new ScatterplotLayer({
      id: 'scatter',
      data: myData,
      getPosition: d => d.coordinates,
      getRadius: 100,
      getFillColor: [255, 0, 0, 128],
      pickable: true
    })
  ];

  return (
    <DeckGL
      viewState={viewState}
      onViewStateChange={({viewState}) => setViewState(viewState)}
      controller={true}
      layers={layers}
      style={{ width: '100%', height: '600px' }}
    >
      <Map
        reuseMaps
        mapStyle="mapbox://styles/mapbox/light-v9"
        mapboxAccessToken={process.env.REACT_APP_MAPBOX_TOKEN}
      />
    </DeckGL>
  );
}

Using React Widgets

import React from 'react';
import DeckGL, { ZoomWidget, CompassWidget, FullscreenWidget } from '@deck.gl/react';

function MapWithWidgets() {
  return (
    <div style={{ position: 'relative', width: '100%', height: '600px' }}>
      <DeckGL
        initialViewState={{
          longitude: -122.4,
          latitude: 37.8,
          zoom: 10
        }}
        controller={true}
        layers={layers}
        style={{ width: '100%', height: '100%' }}
      />
      <ZoomWidget placement="top-left" />
      <CompassWidget placement="top-right" />
      <FullscreenWidget placement="bottom-right" />
    </div>
  );
}

TypeScript Integration

import React from 'react';
import DeckGL from '@deck.gl/react';
import { Layer, PickingInfo } from 'deck.gl';

interface MapProps {
  layers: Layer[];
  onDataHover?: (info: PickingInfo) => void;
}

const TypedMap: React.FC<MapProps> = ({ layers, onDataHover }) => {
  return (
    <DeckGL
      initialViewState={{
        longitude: -122.4,
        latitude: 37.8,
        zoom: 10
      }}
      controller={true}
      layers={layers}
      onHover={onDataHover}
      style={{ width: '100%', height: '400px' }}
    />
  );
};

Component Lifecycle

The DeckGL component follows React lifecycle patterns:

Mounting: Creates deck.gl instance and WebGL context
Updating: Updates layers and view state when props change
Unmounting: Cleans up WebGL resources and event listeners

Performance optimizations:

Layer instances are reused when possible
Deep comparison prevents unnecessary re-renders
WebGL context is preserved across updates