reflex-react-globe-gl

react-globe.gl for Reflex: 3D globe data visualization (ThreeJS/WebGL) written in pure Python.

• Complete API: every prop and callback of react-globe.gl 2.38 — globe, points, arcs, polygons, paths, heatmaps, hex bins, hexed polygons, tiles, particles, rings, labels, HTML elements, 3D objects and custom layers — plus animate_in, wait_for_globe_ready and renderer_config.
• Reflex-friendly events: callbacks receive plain, JSON-safe dicts (the ThreeJS internals, DOM events and circular references are stripped in the browser).
• Responsive: fills its container by default (no more window-sized canvas).
• Declarative imperative API: camera (point_of_view), orbit controls (auto_rotate, …), animation_paused and globe_material_options are regular props bound to your state.
• Actions for the imperative methods (fly_to, get_point_of_view, get_screen_coords, …) usable directly as event triggers or returned from event handlers.
• Helpers to write accessor functions from Python: js, constant, attr, color_scale, tooltip, tile_url, three_mesh, three_material.

Installation

pip install reflex-react-globe-gl
# or
uv add reflex-react-globe-gl

Requires reflex>=0.9.12. The npm packages (react-globe.gl@2.38.0, three@0.186.0) are installed automatically by Reflex the first time the app compiles.

Quick start

import reflex as rx
import reflex_react_globe_gl as rg

IMG = "https://cdn.jsdelivr.net/npm/three-globe/example/img"


class State(rx.State):
    cities: list[dict] = [
        {"name": "Lagos", "lat": 6.52, "lng": 3.38, "size": 0.3},
        {"name": "Paris", "lat": 48.86, "lng": 2.35, "size": 0.5},
        {"name": "Tokyo", "lat": 35.68, "lng": 139.69, "size": 0.8},
    ]
    selected: str = ""

    @rx.event
    def select(self, city: dict):
        self.selected = city["name"]
        return rg.fly_to("globe", city["lat"], city["lng"], altitude=1.2)


def index() -> rx.Component:
    return rx.box(
        rg.globe(
            id="globe",
            globe_image_url=f"{IMG}/earth-night.jpg",
            background_image_url=f"{IMG}/night-sky.png",
            points_data=State.cities,
            point_altitude="size",          # attribute name
            point_color=rg.constant("orange"),  # constant value
            point_radius=0.6,
            point_label="name",
            on_point_click=State.select,
            auto_rotate=True,
            auto_rotate_speed=0.4,
        ),
        rx.text("Selected: ", State.selected, position="absolute", top="1em", left="1em"),
        height="100vh",
        position="relative",
    )


app = rx.App()
app.add_page(index)

Concepts

Sizing

By default the globe fills its container (width: 100%; height: 100%, observed with a ResizeObserver). Give the parent a height (e.g. height="100vh") or style the globe itself (style={"height": "600px"} sizes the container). Explicit pixel width / height props (rg.globe(..., height=600)) override the measured size.

Accessor props

Like upstream, accessor props (point_lat, arc_color, hex_altitude, …) accept:

A plain string is always an attribute name, so constant strings (colors!) need rg.constant("red").

Accessor functions run in the browser. They can reference state vars through f-strings and are re-applied whenever those vars change:

polygon_cap_color=rg.js(
    f"d => d.properties.ADMIN === {State.hovered} ? 'steelblue' : 'rgba(200, 0, 0, 0.6)'"
),

Helpers:

Inside rg.js you can use the global window.ReflexGlobe namespace, which exposes THREE, colorScale, PALETTES and get(id) (the globe handle, e.g. for getCoords).

Events

All layer callbacks are exposed with snake_case names (on_point_click, on_arc_hover, on_hex_polygon_right_click, on_custom_layer_click, …) plus on_globe_ready, on_globe_click, on_globe_right_click and on_zoom. Handlers receive JSON-safe values and may accept only a prefix of the arguments:

Keys starting with __ and keys listed in event_data_exclude (default ["geometry"], so GeoJSON geometries are not shipped over the websocket on every hover) are removed from datums; arrays are capped at 2000 items. Regular DOM events (on_click, on_mouse_move, …) go to the container.

Reflex extensions

Imperative actions

Give the globe an id and use the actions (they are rx.call_script event specs):

rx.button("Tokyo", on_click=rg.fly_to("globe", 35.68, 139.69, altitude=1.2, transition_ms=1500))
rx.button("Where am I?", on_click=rg.get_point_of_view("globe", State.receive_pov))

Performance tips

• Keep large datasets in state and load them in on_load; data identity is preserved between renders, so layers are only rebuilt when the data actually changes.
• Accessors without state vars are stabilized automatically; accessors that embed state vars are re-applied when the component re-renders. To switch between a few fixed functions, prefer rx.cond / rx.match over embedding the var (see the tiles demo).
• hex_bin_merge=True, points_merge=True and enable_pointer_interaction=False trade interactivity for speed on very large datasets.

Demo app

react_globe_gl_demo/ is a multi-page Reflex app that exercises the whole API:

git clone https://github.com/ecrespo/reflex-react-globe-gl
cd reflex-react-globe-gl
uv venv && uv pip install -e ".[dev]"
cd react_globe_gl_demo
uv run reflex run

Globe textures are loaded from jsDelivr. To serve them locally, copy the images from three-globe/example/img into react_globe_gl_demo/assets/img/ and run with GLOBE_IMG_BASE=/img uv run reflex run.

Development

uv pip install -e ".[dev]"
uv run pytest                      # Python + JS wrapper tests (the latter need node)
uv run reflex component build      # generates .pyi stubs, builds sdist + wheel into dist/

Project layout:

custom_components/reflex_react_globe_gl/
├── react_globe_gl.py   # the Globe component (all props / events)
├── globe_wrapper.js    # React wrapper around react-globe.gl (sizing, events, registry…)
├── helpers.py          # js / constant / color_scale / tooltip / tile_url / three_mesh…
└── actions.py          # fly_to / get_point_of_view / set_controls / run_js…
react_globe_gl_demo/    # demo app
tests/                  # pytest suite

Credits

• react-globe.gl, globe.gl and three-globe by Vasco Asturiano (MIT).
• Demo datasets from Natural Earth and the react-globe.gl examples.

License

MIT © Ernesto Crespo