Tile Selector

pick map tiles by clicking or shift-dragging, and round-trip them to Python.

---

.. llms_copy::Tile Selector

.. toc::

Overview

dl2.TileSelector is a map control that turns the map into a tile picker. While it is armed the cursor becomes a crosshair, a dashed outline tracks the tile under the pointer at the current zoom, and:

• click a tile to add or remove it from the selection
• shift-drag a box to capture every tile inside it

Place it as a child of dl2.Map, anywhere among the other layers.

The data boundary

Each selected tile round-trips to Python as a dict:

``python { "z": 11, "x": 470, "y": 843, "url": "https://tile.openstreetmap.org/11/470/843.png", "bounds": [south, west, north, east], } ``

tileUrl decides which template those url values are built from — it does not have to match the dl2.TileLayer you are displaying. The demo below renders CARTO light tiles but hands back OpenStreetMap PNG URLs, which is the usual shape when the map is a picker for some other tileset.

Selections are keyed by z/x/y, so panning and zooming never lose them.

Props

| Prop | Type | Default | What it does | |------|------|---------|--------------| | selectedTiles | list of dicts | [] | The selection. [MUTABLE] — an output (user clicks) *and* an input (write [] to clear). | | tileUrl | string | OSM {z}/{x}/{y} | Template the returned url values are built from. | | position | string | 'topleft' | topleft / topright / bottomleft / bottomright. | | hoverColor | string | '#fa5252' | Colour of the dashed outline under the cursor. | | selectedColor | string | '#228be6' | Stroke and fill of selected-tile rectangles and the box-drag preview. |

Because selectedTiles is [MUTABLE], a plain callback both reads the user's picks and pushes new state back — the Clear button in the demo is one line.

Live demo

.. exec::docs.tile-selector.example :code: false

Source

```python

File: docs/tile-selector/example.py

""" TileSelector — pick tiles off the map by clicking or shift-dragging.

dl2.TileSelector is a map control. While it is armed the cursor becomes a crosshair, a dashed outline tracks the tile under the pointer at the current zoom, and:

• click a tile to add / remove it from the selection • shift-drag a box to capture every tile inside it

Each selected tile round-trips to Python as {z, x, y, url, bounds}, where bounds is [south, west, north, east]. Selections are keyed by z/x/y, so they survive panning and zooming.

selectedTiles is [MUTABLE] — it is both an output (the user's clicks) and an input (the Clear button below writes [] straight back into it). """

import dash_leaflet2 as dl2 import dash_mantine_components as dmc from dash import Input, Output, callback, html, no_update from dash_iconify import DashIconify

from dl2_tiles import USGS_TOPO, register_theme_swap from dl2_locations import AUSTIN from dl2_shared import code_panel, info_panel

Basemap pair for this page — dl2_tiles owns the light/dark wiring.

TILES = USGS_TOPO

The template the PICKED tile URLs are built from. Deliberately not the

basemap: this page's point is that the two are independent.

OSM = "https://tile.openstreetmap.org/{z}/{x}/{y}.png"

CODE = """import dash_leaflet2 as dl2

dl2.Map( center=[30.2672, -97.7431], zoom=11, children=[ dl2.TileLayer(url=OSM), dl2.TileSelector( id="tile-picker", position="topright", tileUrl=OSM, # which tileset the picked URLs point at hoverColor="#fa5252", # dashed outline under the cursor selectedColor="#228be6", ), ], )

@callback(Output("out", "children"), Input("tile-picker", "selectedTiles")) def show(tiles): return f"{len(tiles or [])} tiles selected" """

def _tile_row(tile): """One selected tile as a table row: z/x/y, bounds, and its URL.""" s, w, n, e = tile.get("bounds") or [0, 0, 0, 0] return dmc.TableTr( [ dmc.TableTd( dmc.Code(f"{tile['z']}/{tile['x']}/{tile['y']}"), ), dmc.TableTd( dmc.Text(f"{s:.4f}, {w:.4f} → {n:.4f}, {e:.4f}", size="xs", c="dimmed", ff="monospace"), ), dmc.TableTd( dmc.Anchor( dmc.Group( [DashIconify(icon="tabler:photo", width=14), dmc.Text("PNG", size="xs")], gap=4, ), href=tile.get("url", "#"), target="_blank", ), style={"textAlign": "center"}, ), ] )

component is the name the .. exec:: directive looks for.

component = dmc.Stack( [ dmc.Alert( dmc.Stack( [ dmc.Text( "Click the crosshair button in the map's top-right corner to arm " "the selector, then click tiles — or hold Shift and drag a box.", size="sm", ), dmc.Text( "Zoom changes the tile grid; already-picked tiles stay picked " "because each one is keyed by z/x/y.", size="sm", c="dimmed", ), ], gap=4, ), title="How to use it", color="blue", variant="light", icon=DashIconify(icon="tabler:hand-click"), ), dmc.Paper( dl2.Map( id="ts-map", center=AUSTIN.center, zoom=11, style={"height": "58vh", "width": "100%"}, children=[ dl2.TileLayer(id="ts-tile", **TILES.kwargs("light")), dl2.TileSelector( id="ts-picker", position="topright", # The URLs handed back in selectedTiles point at THIS # template — it does not have to be the tileset you are # displaying. Here we show USGS Topo but hand back OSM PNGs. tileUrl=OSM, hoverColor="#fa5252", selectedColor="#228be6", ), ], ), shadow="sm", radius="md", withBorder=True, style={"overflow": "hidden"}, ), dmc.Group( [ dmc.Button( "Clear selection", id="ts-clear", variant="light", color="red", leftSection=DashIconify(icon="tabler:trash", width=16), ), html.Div(id="ts-count"), ], justify="space-between", align="center", ), info_panel("Selected tiles", html.Div(id="ts-table")), code_panel("Usage", CODE), ], gap="md", )

@callback( Output("ts-count", "children"), Output("ts-table", "children"), Input("ts-picker", "selectedTiles"), ) def show_selection(tiles): tiles = tiles or [] badge = dmc.Badge( f"{len(tiles)} tile{'' if len(tiles) == 1 else 's'} selected", color="blue" if tiles else "gray", variant="light", size="lg", ) if not tiles: return badge, dmc.Text( "Nothing selected yet — arm the control and click a tile.", c="dimmed", size="sm", )

table = dmc.Table( [ dmc.TableThead( dmc.TableTr( [ dmc.TableTh("z/x/y"), dmc.TableTh("bounds (S, W → N, E)"), dmc.TableTh("tile", style={"textAlign": "center"}), ] ) ), # Newest first, and capped — a shift-drag at low zoom can select a # lot of tiles and this is a doc page, not a data grid. dmc.TableTbody([_tile_row(t) for t in list(reversed(tiles))[:25]]), ], striped=True, highlightOnHover=True, ) footer = ( dmc.Text(f"Showing the 25 most recent of {len(tiles)}.", size="xs", c="dimmed", mt="xs") if len(tiles) > 25 else None ) return badge, dmc.Stack([table, footer], gap=0)

@callback( Output("ts-picker", "selectedTiles"), Input("ts-clear", "n_clicks"), prevent_initial_call=True, ) def clear_selection(n_clicks): """Python → map: writing the [MUTABLE] prop clears the component's state.""" return [] if n_clicks else no_update

Light/dark basemap, driven off the color-scheme store.

register_theme_swap("ts-tile", TILES) ```

:defaultExpanded: false :withExpandedButton: true

---

*Source: /tile-selector*