Skip to content



Bases: BaseArrowLayer

Render text labels at given coordinates.

auto_highlight class-attribute instance-attribute

auto_highlight = tag(sync=True)

When true, the current object pointed to by the mouse pointer (when hovered over) is highlighted with highlightColor.

Requires pickable to be True.

  • Type: bool
  • Default: False

background_padding class-attribute instance-attribute

background_padding = tag(sync=True)

The padding of the background.

  • If an array of 2 is supplied, it is interpreted as [padding_x, padding_y] in pixels.
  • If an array of 4 is supplied, it is interpreted as [padding_left, padding_top, padding_right, padding_bottom] in pixels.

default [0, 0, 0, 0]

billboard class-attribute instance-attribute

billboard = tag(sync=True)

If true, the text always faces camera. Otherwise the text faces up (z).

  • Type: bool
  • Default: True

character_set class-attribute instance-attribute

character_set = tag(sync=True)

Specifies a list of characters to include in the font. If set to 'auto', will be automatically generated from the data set.

default (ASCII characters 32-128)

extensions class-attribute instance-attribute

extensions = tag(sync=True, **widget_serialization)

A list of layer extension objects to add additional features to a layer.

font_family class-attribute instance-attribute

font_family = tag(sync=True)

CSS font family

default 'Monaco, monospace'

font_settings class-attribute instance-attribute

font_settings = tag(sync=True)

Advance options for fine tuning the appearance and performance of the generated shared fontAtlas.

font_weight class-attribute instance-attribute

font_weight = tag(sync=True)

CSS font weight

default 'normal'

get_alignment_baseline class-attribute instance-attribute

get_alignment_baseline = tag(sync=True)

Vertical alignment accessor

default 'center'

get_angle class-attribute instance-attribute

get_angle = FloatAccessor(None, allow_none=True)

Label rotation accessor, in degrees

default 0

get_background_color class-attribute instance-attribute

get_background_color = ColorAccessor(None, allow_none=True)

Background color accessor.

default [255, 255, 255, 255]

get_border_color class-attribute instance-attribute

get_border_color = ColorAccessor(None, allow_none=True)

Border color accessor.

default [0, 0, 0, 255]

get_border_width class-attribute instance-attribute

get_border_width = FloatAccessor(None, allow_none=True)

Border width accessor.

default 0

get_color class-attribute instance-attribute

get_color = ColorAccessor(None, allow_none=True)

Label color accessor

default [0, 0, 0, 255]

get_pixel_offset class-attribute instance-attribute

get_pixel_offset = tag(sync=True)

Label offset from the anchor position, [x, y] in pixels

default [0, 0]

get_size class-attribute instance-attribute

get_size = FloatAccessor(None, allow_none=True)

Label size accessor

default 32

get_text class-attribute instance-attribute

get_text = TextAccessor(None, allow_none=True)

Label text accessor

get_text_anchor class-attribute instance-attribute

get_text_anchor = tag(sync=True)

Horizontal alignment accessor

default 'middle'

line_height class-attribute instance-attribute

line_height = tag(sync=True)

A unitless number that will be multiplied with the current text size to set the line height.

max_width class-attribute instance-attribute

max_width = tag(sync=True)

A unitless number that will be multiplied with the current text size to set the width limit of a string.

If specified, when the text is longer than the width limit, it will be wrapped into multiple lines using the strategy of wordBreak.

default -1

opacity class-attribute instance-attribute

opacity = tag(sync=True)

The opacity of the layer.

  • Type: float. Must range between 0 and 1.
  • Default: 1

outline_color class-attribute instance-attribute

outline_color = tag(sync=True)

Color of outline around the text, in [r, g, b, [a]]. Each channel is a number between 0-255 and a is 255 if not supplied.

default [0, 0, 0, 255]

outline_width class-attribute instance-attribute

outline_width = tag(sync=True)

Width of outline around the text, relative to the text size. Only effective if fontSettings.sdf is true.

default 0

pickable class-attribute instance-attribute

pickable = tag(sync=True)

Whether the layer responds to mouse pointer picking events.

This must be set to True for tooltips and other interactive elements to be available. This can also be used to only allow picking on specific layers within a map instance.

Note that picking has some performance overhead in rendering. To get the absolute best rendering performance with large data (at the cost of removing interactivity), set this to False.

  • Type: bool
  • Default: True

selected_index class-attribute instance-attribute

selected_index = tag(sync=True)

The positional index of the most-recently clicked on row of data.

You can use this to access the full row of data from a GeoDataFrame


Setting a value here from Python will do nothing. This attribute only exists to be updated from JavaScript on a map click. Note that pickable must be True (the default) on this layer for the JavaScript onClick handler to work; if pickable is set to False, selected_index will never update.

Note that you can use observe to call a function whenever a new value is received from JavaScript. Refer here for an example.

size_max_pixels class-attribute instance-attribute

size_max_pixels = tag(sync=True)

The maximum size in pixels. When using non-pixel sizeUnits, this prop can be used to prevent the icon from getting too big when zoomed in.

  • Type: float, optional
  • Default: None

size_min_pixels class-attribute instance-attribute

size_min_pixels = tag(sync=True)

The minimum size in pixels. When using non-pixel sizeUnits, this prop can be used to prevent the icon from getting too small when zoomed out.

  • Type: float, optional
  • Default: 0

size_scale class-attribute instance-attribute

size_scale = tag(sync=True)

Text size multiplier.

  • Type: float.
  • Default: 1

size_units class-attribute instance-attribute

size_units = tag(sync=True)

The units of the size, one of 'meters', 'common', and 'pixels'. default 'pixels'. See unit system.

  • Type: str, optional
  • Default: 'pixels'

table class-attribute instance-attribute

table = PyarrowTableTrait(allowed_geometry_types={POINT})

A GeoArrow table with a Point or MultiPoint column.

This is the fastest way to plot data from an existing GeoArrow source, such as geoarrow-rust or geoarrow-pyarrow.

If you have a GeoPandas GeoDataFrame, use from_geopandas instead.

visible class-attribute instance-attribute

visible = tag(sync=True)

Whether the layer is visible.

Under most circumstances, using the visible attribute to control the visibility of layers is recommended over removing/adding the layer from the Map.layers list.

In particular, toggling the visible attribute will persist the layer on the JavaScript side, while removing/adding the layer from the Map.layers list will re-download and re-render from scratch.

  • Type: bool
  • Default: True

word_break class-attribute instance-attribute

word_break = tag(sync=True)

Available options are break-all and break-word. A valid maxWidth has to be provided to use wordBreak.

default 'break-word'

from_duckdb classmethod

    sql: Union[str, DuckDBPyRelation],
    con: Optional[DuckDBPyConnection] = None,
    crs: Optional[Union[str, CRS]] = None,
    **kwargs: Unpack[BaseLayerKwargs]
) -> Self

Construct a Layer from a duckdb-spatial query.

DuckDB Spatial does not currently expose coordinate reference system information, so the user must ensure that data has been reprojected to EPSG:4326 or pass in the existing CRS of the data in the crs keyword parameter.


  • sql (Union[str, DuckDBPyRelation]) –

    The SQL input to visualize. This can either be a string containing a SQL query or the output of the duckdb sql function.

  • con (Optional[DuckDBPyConnection], default: None ) –

    The current DuckDB connection. This is required when passing a str to the sql parameter or when using a non-global DuckDB connection. Defaults to None.

Other Parameters:

  • crs (Optional[Union[str, CRS]]) –

    The CRS of the input data. This can either be a string passed to pyproj.CRS.from_user_input or a pyproj.CRS object. Defaults to None.


  • Self

    A Layer with the initialized data.

from_geopandas classmethod

    gdf: GeoDataFrame,
    auto_downcast: bool = True,
    **kwargs: Unpack[BaseLayerKwargs]
) -> Self

Construct a Layer from a geopandas GeoDataFrame.

The GeoDataFrame will be reprojected to EPSG:4326 if it is not already in that coordinate system.


  • gdf (GeoDataFrame) –

    The GeoDataFrame to set on the layer.

Other Parameters:


  • Self

    A Layer with the initialized data.