Skip to content

TileLayer

TileLayer #

Bases: MapLayer

Displays square raster images in a continuous grid, sourced from the provided url_template and fallback_url.

Typically the first layer to be added to a Map, as it provides the tiles on which other layers are displayed.

RAISES DESCRIPTION
AssertionError

If one or more of the following is negative: tile_size, min_native_zoom, max_native_zoom, zoom_offset, max_zoom, min_zoom

additional_options #

additional_options: dict[str, str] = field(
    default_factory=dict
)

Static information that should replace placeholders in the url_template. Applying API keys, for example, is a good usecase of this parameter.

Example 
TileLayer(
    url_template="https://api.tiles.mapbox.com/v4/{id}/{z}/{x}/{y}{r}.png?access_token={accessToken}",
    additional_options={
        'accessToken': '<ACCESS_TOKEN_HERE>',
        'id': 'mapbox.streets',
    },
),

badge #

badge: BadgeValue | None = None

A badge to show on top of this control.

col #

col: ResponsiveNumber = 12

If a parent of this control is a ResponsiveRow, this property is used to determine how many virtual columns of a screen this control will span.

Can be a number or a dictionary configured to have a different value for specific breakpoints, for example col={"sm": 6}.

This control spans the 12 virtual columns by default.

/// details | Dimensions type: info | Breakpoint | Dimension | |---|---| | xs | <576px | | sm | ≥576px | | md | ≥768px | | lg | ≥992px | | xl | ≥1200px | | xxl | ≥1400px | ///

data #

data: Any = skip_field()

Arbitrary data of any type.

disabled #

disabled: bool = False

Every control has disabled property which is False by default - control and all its children are enabled.

Note

The value of this property will be propagated down to all children controls recursively.

/// details | Example type: example For example, if you have a form with multiple entry controls you can disable them all together by disabling container:

ft.Column(
    disabled = True,
    controls=[
        ft.TextField(),
        ft.TextField()
    ]
)
///

display_mode #

display_mode: TileDisplay = field(
    default_factory=lambda: FadeInTileDisplay()
)

Defines how tiles are displayed on the map.

enable_retina_mode #

enable_retina_mode: bool = False

Whether to enable retina mode. Retina mode improves the resolution of map tiles, particularly on high density displays.

enable_tms #

enable_tms: bool = False

Whether to inverse Y-axis numbering for tiles. Turn this on for TMS services.

error_image_src #

error_image_src: str | None = None

The source of the tile image to show in place of the tile that failed to load.

See on_image_error property for details on the error.

evict_error_tile_strategy #

evict_error_tile_strategy: (
    TileLayerEvictErrorTileStrategy | None
) = NONE

If a tile was loaded with error, the tile provider will be asked to evict the image based on this strategy.

expand #

expand: bool | int | None = None

Specifies whether/how this control should expand to fill available space in its parent layout.

More information here.

Note

Has effect only if the direct parent of this control is one of the following controls, or their subclasses: Column, Row, View, Page.

expand_loose #

expand_loose: bool = False

Allows the control to expand along the main axis if space is available, but does not require it to fill all available space.

More information here.

Note

If expand_loose is True, it will have effect only if:

  • expand is not None and
  • the direct parent of this control is one of the following controls, or their subclasses: Column, Row, View, Page.

fallback_url #

fallback_url: str | None = None

Fallback URL template, used if an error occurs when fetching tiles from the url_template.

Note that specifying this (non-none) will result in tiles not being cached in memory. This is to avoid issues where the url_template is flaky, to prevent different tilesets being displayed at the same time.

It is expected that this follows the same retina support behaviour as url_template.

keep_buffer #

keep_buffer: int = 2

When panning the map, keep this many rows and columns of tiles before unloading them.

key #

key: KeyValue | None = None

max_native_zoom #

max_native_zoom: int = 19

Maximum zoom number supported by the tile source has available.

Tiles from above this zoom level will not be displayed, instead tiles at this zoom level will be displayed and scaled.

Most tile servers support up to zoom level 19, which is the default. Otherwise, this should be specified.

Note

Must be greater than or equal to 0.0.

max_zoom #

max_zoom: Number = float('inf')

The maximum zoom level up to which this layer will be displayed (inclusive). The main usage for this property is to display a different TileLayer when zoomed far in.

Prefer max_native_zoom for setting the maximum zoom level supported by the tile source.

Typically set to infinity so that there are tiles always displayed.

Note

Must be greater than or equal to 0.0.

min_native_zoom #

min_native_zoom: int = 0

Minimum zoom level supported by the tile source.

Tiles from below this zoom level will not be displayed, instead tiles at this zoom level will be displayed and scaled.

This should usually be 0 (as default), as most tile sources will support zoom levels onwards from this.

Note

Must be greater than or equal to 0.0.

min_zoom #

min_zoom: Number = 0.0

The minimum zoom level at which this layer is displayed (inclusive). Typically 0.0.

Note

Must be greater than or equal to 0.0.

on_image_error #

on_image_error: ControlEventHandler[TileLayer] | None = None

Fires if an error occurs when fetching the tiles.

Event handler argument data property contains information about the error.

opacity #

opacity: Number = 1.0

Defines the transparency of the control.

Value ranges from 0.0 (completely transparent) to 1.0 (completely opaque without any transparency).

page #

page: Page | BasePage | None

The page to which this control belongs to.

pan_buffer #

pan_buffer: int = 1

When loading tiles only visible tiles are loaded by default. This option increases the loaded tiles by the given number on both axis which can help prevent the user from seeing loading tiles whilst panning. Setting the pan buffer too high can impact performance, typically this is set to 0 or 1.

parent #

parent: BaseControl | None

The direct ancestor(parent) of this control.

It defaults to None and will only have a value when this control is mounted (added to the page tree).

The Page control (which is the root of the tree) is an exception - it always has parent=None.

rtl #

rtl: bool = False

Whether the text direction of the control should be right-to-left (RTL).

subdomains #

subdomains: list[str] = field(
    default_factory=lambda: ["a", "b", "c"]
)

List of subdomains used in the URL template.

For example, if subdomains is set to ["a", "b", "c"] and the url_template is "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png", the resulting tile URLs will be:

  • "https://a.tile.openstreetmap.org/{z}/{x}/{y}.png"
  • "https://b.tile.openstreetmap.org/{z}/{x}/{y}.png"
  • "https://c.tile.openstreetmap.org/{z}/{x}/{y}.png"

tile_bounds #

tile_bounds: MapLatitudeLongitudeBounds | None = None

Defines the bounds of the map. Only tiles that fall within these bounds will be loaded.

tile_size #

tile_size: int = 256

The size in pixels of each tile image. Should be a positive power of 2.

Note

Must be greater than or equal to 0.0.

tooltip #

tooltip: TooltipValue | None = None

The tooltip ot show when this control is hovered over.

url_template #

url_template: str

The URL template is a string that contains placeholders, which, when filled in, create a URL/URI to a specific tile.

user_agent_package_name #

user_agent_package_name: str = 'unknown'

The package name of the user agent.

visible #

visible: bool = True

Every control has visible property which is True by default - control is rendered on the page. Setting visible to False completely prevents control (and all its children if any) from rendering on a page canvas. Hidden controls cannot be focused or selected with a keyboard or mouse and they do not emit any events.

zoom_offset #

zoom_offset: Number = 0.0

The zoom number used in tile URLs will be offset with this value.

Note

Must be greater than or equal to 0.0.

zoom_reverse #

zoom_reverse: bool = False

Whether the zoom number used in tile URLs will be reversed (max_zoom - zoom instead of zoom).

before_event #

before_event(e: ControlEvent)

before_update #

before_update()

build #

build()

Called once during control initialization to define its child controls. self.page is available in this method.

clean #

clean() -> None

did_mount #

did_mount()

init #

init()

is_isolated #

is_isolated()

update #

update() -> None

will_unmount #

will_unmount()