DOCSEARCHbyAlgolia
Submit Docs

react-globe.gl

repository·master·Indexed 22 days ago

https://github.com/vasturiano/react-globe.gl

A React component for 3D globe data visualization using ThreeJS and WebGL. It supports multiple visualization layers, including points, arcs, polygons, paths, and heatmaps, allowing for high-performance rendering of data on a spherical projection.

Tokens
16.1K
Snippets
14
Records
38
Agent score
71%

What's inside react-globe.gl

  1. Quick start with react-globe.gl

    master

    To use react-globe.gl in a React application, import the Globe component from the package. You can then render the component and pass data to its props (e.g., pointsData) to visualize information on a 3D globe.

    Using npm/yarn

    import Globe from 'react-globe.gl';

    Using a script tag

    <script src="//cdn.jsdelivr.net/npm/react-globe.gl"></script>

    Rendering the component

    ReactDOM.render(
  <Globe
    pointsData={myData}
  />, 
  myDOMElement
);
    import Globe from 'react-globe.gl';

// ...

ReactDOM.render(
  <Globe
    pointsData={myData}
  />, 
  myDOMElement
);

  2. Configure the Polygons Layer

    master

    The Polygons Layer represents shapes on the globe as extruded cones. This is ideal for choropleth maps or highlighting specific regions.

    Data and Geometry

    • polygonsData: An array of objects representing the polygon shapes.
    • polygonGeoJsonGeometry: Accessor for the GeoJson geometry. Must return a GeoJson object with type (must be Polygon or MultiPolygon) and coordinates.
    • polygonLabel: Accessor for the tooltip label (supports plain text or HTML).

    Appearance

    • polygonCapColor: Color of the top surface.
    • polygonCapMaterial: ThreeJS material for the top surface. Takes precedence over polygonCapColor.
    • polygonSideColor: Color of the cone sides.
    • polygonSideMaterial: ThreeJS material for the cone sides. Takes precedence over polygonSideColor.
    • polygonStrokeColor: Color of the perimeter stroke. A falsy value disables stroking.
    • polygonAltitude: Altitude of the cone in globe radius units (0 = flat, 1 = globe radius).
    • polygonCapCurvatureResolution: Resolution (in angular degrees) of the cap surface curvature. Higher values increase smoothness but decrease performance.

    Interactivity and Transitions

    • onPolygonClick(polygon, event, { lat, lng, altitude }): Left-click callback.
    • onPolygonRightClick(polygon, event, { lat, lng, altitude }): Right-click callback.
    • onPolygonHover(polygon, prevPolygon): Mouseover callback.
    • polygonsTransitionDuration: Duration in ms for animating altitude changes.

  3. Configure the Paths Layer

    master

    The Paths Layer represents a list of lines connecting coordinate pairs. You can customize the appearance, animation, and interaction of these paths using the following props:

    Data and Coordinates

    • pathsData: Array of path objects.
    • pathPoints: Accessor for the set of points defining the line. Defaults to [lat, lng] arrays.
    • pathPointLat, pathPointLng, pathPointAlt: Accessors for latitude, longitude, and altitude (in globe radius units, where 0 is ground and 1 is globe radius).
    • pathResolution: Angular resolution in degrees. Lower values create smoother curves but cost more performance.

    Styling and Appearance

    • pathColor: Accessor for line color. Supports strings, arrays of colors (for gradients), or interpolator functions.
    • pathStroke: Line diameter in angular degrees. If null or undefined, it uses a standard ThreeJS Line (constant 1px width). Otherwise, it uses FatLine for variable width.
    • pathDashLength, pathDashGap, pathDashInitialGap: Controls for dashed line segments (relative to total line length).
    • pathDashAnimateTime: Duration in ms to animate dash motion.
    • pathTransitionDuration: Duration in ms for animating changes between path datasets.

    Interactions

    • onPathClick(path, event, { lat, lng, altitude }): Left-click callback.
    • onPathRightClick(path, event, { lat, lng, altitude }): Right-click callback.
    • onPathHover(path, prevPath): Mouseover callback.

  4. Configure the Rings Layer

    master

    The Rings Layer displays self-propagating ripple rings that move through the spherical surface from a central point.

    Key properties:

    • ringsData: Array of data points for the rings.
    • ringLat, ringLng, ringAltitude: Accessors for the circle's center coordinates and altitude.
    • ringColor: Stroke color. Supports single colors, arrays of colors for radial gradients, or interpolator functions.
    • ringMaxRadius: Maximum outer radius in angular degrees before the ring is removed.
    • ringPropagationSpeed: Velocity in degrees/second. Negative values cause rings to propagate inwards.
    • ringRepeatPeriod: Interval in ms between consecutive concentric circles. Set $\le 0$ to emit only a single ring.
    • ringResolution: Geometric resolution (number of slice segments). Higher values are smoother but more expensive.

  5. Configure the Heatmaps Layer

    master

    The Heatmaps Layer uses Gaussian KDE to represent point density as global heatmaps with varying color and altitude.

    Data and Density

    • heatmapsData: Array of heatmap datasets.
    • heatmapPoints: Accessor for the points defining the heatmap. Defaults to [lat, lng] arrays.
    • heatmapPointLat, heatmapPointLng: Accessors for latitude and longitude.
    • heatmapPointWeight: Accessor for point weight, determining its influence on surrounding density.
    • heatmapBandwidth: The Gaussian kernel bandwidth in angular degrees. Narrower values create 'spiky' maps; broader values create smoother curves.
    • heatmapColorSaturation: Multiplier for normalized density ([0,1]) before color interpolation. Useful for dampening outliers.

    Visuals and Altitude

    • heatmapColorFn: Accessor for the color interpolator. Receives a number (typically 0 to 1) and returns a color string. Defaults to a Turbo colormap with fading opacity.
    • heatmapBaseAltitude: The floor altitude of the heatmap (in globe radius units).
    • heatmapTopAltitude: The peak altitude of the heatmap. If equal to heatmapBaseAltitude, the heatmap is flat. If set, density variations define the curves between base and top.
    • heatmapsTransitionDuration: Duration in ms for animating changes. New heatmaps rise from the ground and fade in.

    Interactions

    • onHeatmapClick(heatmap, event, { lat, lng, altitude }): Left-click callback.
    • onHeatmapRightClick(heatmap, event, { lat, lng, altitude }): Right-click callback.
    • onHeatmapHover(heatmap, prevHeatmap): Mouseover callback.

  6. Configure the Custom Layer

    master

    The Custom Layer provides a way to render custom 3D objects with optimized update capabilities. This is ideal for high-performance scenarios where objects need to be updated without being destroyed and recreated.

    Key properties include:

    • customLayerData: Array of items to represent.
    • customThreeObject: Accessor function that returns a ThreeJS Object3d.
    • customThreeObjectUpdate: An accessor function used to update existing objects for better performance. The signature is (obj, objData) => { ... }, where obj is the ThreeJS object and objData is the new data.
    • customLayerLabel: Accessor for tooltip labels.

  7. Configure the Arcs Layer

    master

    The Arcs Layer represents links between two points on the globe as curved lines. You can control the data, appearance, and interactivity of these arcs using the following props:

    Data and Coordinates

    • arcsData: An array of objects representing the links.
    • arcStartLat, arcStartLng, arcStartAltitude: Accessors (function, attribute, or constant) for the starting point's latitude, longitude, and altitude.
    • arcEndLat, arcEndLng, arcEndAltitude: Accessors for the ending point's latitude, longitude, and altitude.

    Appearance

    • arcColor: Accessor for the line color. Supports strings, arrays of colors (for gradients), or interpolator functions.
    • arcAltitude: The maximum altitude of the arc (at the midpoint) in globe radius units (0 = ground, 1 = globe radius). If null, altitude is set automatically via arcAltitudeAutoScale.
    • arcAltitudeAutoScale: Scale for automatic altitude based on great-arc distance (only used if arcAltitude is not set).
    • arcStroke: The line's diameter in angular degrees. If null, a constant 1px ThreeJS Line is used. Otherwise, TubeGeometry is used.
    • arcCurveResolution: Number of straight line segments dividing the curve (higher = smoother).
    • arcDashLength, arcDashGap, arcDashInitialGap: Controls for dashed line segments (relative to total line length).
    • arcDashAnimateTime: Duration in ms to animate dash motion from start to end.

    Interactivity and Transitions

    • onArcClick(arc, event, { lat, lng, altitude }): Left-click callback.
    • onArcRightClick(arc, event, { lat, lng, altitude }): Right-click callback.
    • onArcHover(arc, prevArc): Mouseover callback.
    • arcsTransitionDuration: Duration in ms for animating geometry changes.

  8. Configure the Labels Layer

    master

    The Labels Layer allows you to render text labels on the globe. You provide a list of objects via labelsData and use accessor functions or attributes to define their properties.

    Key properties include:

    • labelsData: Array of label objects.
    • labelText: Accessor for the text content (supports plain text or HTML).
    • labelLat / labelLng: Accessors for coordinates.
    • labelAltitude: Altitude in globe radius units.
    • labelSize: Text height in angular degrees.
    • labelColor: Accessor for color.
    • labelIncludeDot: Boolean to show a dot marker at the exact coordinates.
    • labelDotOrientation: Orientation of the label relative to the dot ('right', 'top', or 'bottom').
    • labelsTransitionDuration: Animation duration (ms) for position changes.

  9. Configure the Hexed Polygons Layer

    master

    The Hexed Polygons layer represents polygon shapes (GeoJSON) as a tessellated group of hexagons on the globe.

    Key Configuration Props:

    • hexPolygonsData: Array of polygon shapes.
    • hexPolygonGeoJsonGeometry: Accessor for the GeoJSON geometry (must be Polygon or MultiPolygon).
    • hexPolygonResolution: H3 resolution (0-15) for the hexagons.
    • hexPolygonAltitude: Altitude of the hexagons in globe radius units.
    • hexPolygonUseDots: If true, represents polygon points as circular dots instead of hexagons.
    • hexPolygonDotResolution: Smoothness of circular dots (only used if hexPolygonUseDots is true).
    • hexPolygonColor: Accessor for the color of hexagons within the polygon.
    • onHexPolygonClick: Callback for left-clicks: (polygon, event, { lat, lng, altitude }) => void.

  10. Handle Interaction Events for Layers

    master

    Each layer (Labels, HTML Elements, 3D Objects, and Custom Layer) provides specific callback props for user interactions.

    Common patterns for callbacks:

    • Click: on[Layer]Click(obj, event, { lat, lng, altitude })
    • Right Click: on[Layer]RightClick(obj, event, { lat, lng, altitude })
    • Hover: on[Layer]Hover(obj, prevObj) where obj is the current object under the mouse (or null) and prevObj is the previous object (or null).

  11. Configure the Hex Bin Map Layer

    master

    The Hex Bin Map layer aggregates points into hexagonal 3D prisms using H3 geographic binning.

    Key Configuration Props:

    • hexBinPointsData: Array of points to be aggregated.
    • hexBinResolution: H3 resolution (0-15). Higher values result in smaller hexagons.
    • hexBinPointLat / hexBinPointLng: Accessors for point coordinates.
    • hexBinPointWeight: Accessor for point weight; weights in a bin are summed to determine hexAltitude.
    • hexAltitude: The height of hexagons in globe radius units (0 to 1). Supports an accessor function: ({ points, sumWeight, center: { lat, lng } }) => number.
    • hexMargin: Radial margin (0 to 1) creating gaps between hexagons.
    • hexBinMerge: If true, merges meshes into a single ThreeJS object for performance. Note: Disabling this is required for animations (hexTransitionDuration) and interaction callbacks (onHexClick, onHexRightClick, onHexHover).

  12. Configure the Particles Layer

    master

    The Particles Layer represents groups of particles (as ThreeJS Points) that can be positioned anywhere relative to the globe.

    Key properties:

    • particlesData: Array of particle sets (expected to be an array of arrays of individual particle objects).
    • particlesList: Accessor for the list of particles within a set.
    • particleLat, particleLng, particleAltitude: Accessors for individual particle coordinates.
    • particlesSize: Accessor for the size of all particles in the group.
    • particlesSizeAttenuation: Boolean to attenuate particle size based on camera distance.
    • particlesColor: Color for the group (ignored if particlesTexture is used).
    • particlesTexture: Accessor for a ThreeJS Texture to apply to the group.

    Event Handlers:

    • onParticleClick(particle, event, { lat, lng, altitude })
    • onParticleRightClick(particle, event, { lat, lng, altitude })
    • onParticleHover(particle, prevParticle)