SvgWidget¶

A Kivy widget for displaying SVG content using adaptive rasterization via the kivy.core.svg provider system.

Features

SVG loading from source (local file path or in-memory SVG bytes; AsyncSvgWidget additionally accepts HTTP/HTTPS URLs)
Efficient downscaling using mipmaps (enabled by default)
Re-rasterization at higher resolution when the display scale crosses an internal threshold
Limited runtime document customisation:
- current_color - sets the CSS currentColor value
- element_overrides - per-element visibility and opacity by SVG element id
AsyncSvgWidget adds asynchronous HTTP/HTTPS loading

Difference from the SVG image provider

The SVG image provider (kivy.core.image) lets you use Image(source="file.svg") and renders once at a fixed size. SvgWidget differs in:

Adaptive re-rasterization - re-renders when scaling up beyond threshold
Mipmap-first - mipmaps enabled by default
``current_color`` - CSS currentColor injection not available via the image pipeline
Element overrides - per-element visibility/opacity not available via the image pipeline

Basic usage

from kivy.uix.svg import SvgWidget

svg = SvgWidget(source='diagram.svg', size_hint=(None, None), size=(64, 64))

KV:

SvgWidget:
    source: 'diagram.svg'
    current_color: 1, 0, 0   # red currentColor
    on_load: print('SVG ready')

AsyncSvgWidget:
    source: 'https://example.com/diagram.svg'

SVG icon button

Combine ToggleButtonBehavior with SvgWidget to create a tappable icon that changes colour on toggle. This pattern works with any SVG that uses stroke="currentColor" or fill="currentColor". Most popular svg icon libraries use currentColor by default, including Lucide, Heroicons, and Tabler Icons.

# Python
from kivy.uix.behaviors import ToggleButtonBehavior
from kivy.uix.svg import SvgWidget

class StarIconToggleButton(ToggleButtonBehavior, SvgWidget):
    pass

# KV
<StarIconToggleButton>:
    source: 'star.svg'
    size_hint: None, None
    size: '64dp', '64dp'
    fit_mode: 'contain'
    mipmap: False
    current_color: 'gold' if self.activated else 'grey'

New in version 3.0.0.

class kivy.uix.svg.AsyncSvgWidget(**kwargs)¶

Bases: kivy.uix.svg.SvgWidget

Asynchronous variant of SvgWidget that downloads SVG files from HTTP/HTTPS URLs in a background thread.

Local file paths are loaded synchronously (same behaviour as SvgWidget). Remote URLs are downloaded in a daemon thread; the widget shows loading_texture while the download is in progress.

Note

The loading image and error image are taken from Kivy’s global Loader.loading_image and Loader.error_image, matching AsyncImage. To use a custom image, set these before creating any AsyncSvgWidget:: The loading image supports GIF animation.

from kivy.loader import Loader Loader.loading_image = ‘my_spinner.gif’ Loader.error_image = ‘my_error.png’

Example KV usage:

AsyncSvgWidget:
    source: 'https://example.com/icon.svg'
    on_load: print('downloaded and ready')
    on_error: print('failed:', args[1])

get_norm_image_size()¶

Return the display size after applying fit_mode.

While loading or showing an error placeholder the texture is drawn at its natural size (scale-down behaviour) regardless of fit_mode, so a small spinner GIF is never stretched to fill the widget. Once the SVG is ready the base class logic applies.

static is_uri(filename)¶

Return True if filename is an HTTP or HTTPS URL.

Non-string values (e.g. bytes, pathlib.Path) always return False.

Parameters:: filename – Source value to test.
Return type:: bool

texture_update(*largs)¶: No-op - prevents the inherited synchronous load path.

class kivy.uix.svg.SvgWidget(**kwargs)¶

Bases: kivy.uix.widget.Widget

Widget that displays an SVG document using adaptive rasterization.

The SVG is rasterized to a Texture via the kivy.core.svg provider. The texture is re-created when the display size grows beyond _RERENDER_THRESHOLD times the current raster size, keeping the image sharp at larger scales without wasting GPU memory at smaller ones.

Downscaling is handled efficiently by OpenGL mipmaps (mipmap defaults to True).

get_element_ids()¶

Return a list of all SVG element id values in the document.

The list is built once at load time. Returns an empty list if the SVG has not been loaded yet, and logs a warning.

Return type:: list[str]

get_element_opacity(element_id)¶

Return the current opacity override for element_id.

Returns 1.0 for elements with no opacity override.

Parameters:: element_id (str) – The SVG element id.
Return type:: float

get_norm_image_size()¶

Return the display size of the SVG after applying fit_mode.

Mirrors get_norm_image_size() exactly.

hide_element(element_id)¶

Hide the SVG element with the given id.

Convenience wrapper for set_element_visible(element_id, False).

Parameters:: element_id (str) – The SVG element id attribute value.

is_element_visible(element_id)¶

Return whether the element with element_id is currently visible.

Returns True for elements with no override (SVG default).

Parameters:: element_id (str) – The SVG element id.
Return type:: bool

reload()¶

Discard the current SVG document and reload from source.

Resets loaded and status immediately; the new texture is available after the next successful rasterization.

reset_element_overrides()¶

Clear all element visibility and opacity overrides.

Triggers a re-render that restores all elements to their SVG defaults.

set_element_opacity(element_id, opacity)¶

Set the opacity override for an SVG element by its id.

Stores the override in element_overrides and triggers a re-render. If the SVG is not yet loaded, the override is still stored.

If element_id is not found in the document, a warning is logged.

Parameters:

element_id (str) – The SVG element id.
opacity (float) – Opacity value 0.0 (transparent) - 1.0 (opaque).

set_element_visible(element_id, visible)¶

Set the visibility of an SVG element by its id.

Stores the override in element_overrides and triggers a re-render. If the SVG is not yet loaded, the override is still stored and will be applied when the document loads.

If element_id is not found in the document, a warning is logged but the override is still stored.

Parameters:

element_id (str) – The SVG element id.
visible (bool) – True to show, False to hide.

show_element(element_id)¶

Show the SVG element with the given id.

Convenience wrapper for set_element_visible(element_id, True).

Parameters:: element_id (str) – The SVG element id attribute value.

texture_update(*largs)¶

Load (or reload) the SVG from source and rasterize.

Called automatically when source changes. Can also be called manually to force a reload.

« Stencil View

Switch »

Version

Quick search

Table Of Contents

SvgWidget¶