flet-circular-slider

A circular/radial slider control for Flet, wrapping the sleek_circular_slider Flutter package.

Install

pip install flet-circular-slider

Then register it as a Flet extension in your project's pyproject.toml so the Flutter widget gets compiled:

[project]
dependencies = ["flet-circular-slider>=0.6.0"]

[tool.flet.dev_packages]
flet-circular-slider = ">=0.5.0"

Then run flet build (see Building below). flet run alone won't compile extensions -- you'll get "Unknown control" without a build step.

Quick Start

import flet as ft
from flet_circular_slider import FletCircularSlider

def main(page: ft.Page):
    page.bgcolor = "#1a1a2e"

    slider = FletCircularSlider(
        min=0, max=100, value=25, size=200,
        on_change=lambda e: print(int(e.data)),
    )
    page.add(slider)

ft.run(main)

Programmatic Updates

Set the slider value from Python code -- the widget animates smoothly to the new position:

slider = FletCircularSlider(min=0, max=100, value=25, size=200)
page.add(slider)

# Later, from a timer, another control, or any event:
slider.value = 75
slider.update()  # slider animates to 75

This works for dashboards, timers, or any scenario where Python drives the value. See the root main.py demo app for a full showcase with all features.

Label Formatting

Use label_formatter to transform the numeric value into any string. The callback runs once per step at build time, so the slider displays your formatted labels (e.g. "1h 30m") instead of raw numbers.

def format_duration(minutes: float) -> str:
    m = int(minutes)
    if m == 0:
        return "0m"
    h, rem = divmod(m, 60)
    if h == 0:
        return f"{rem}m"
    return f"{h}h {rem}m" if rem else f"{h}h"

slider = FletCircularSlider(
    min=0, max=200, value=90,
    divisions=200,
    label_formatter=format_duration,
    size=280,
)

divisions is required when using label_formatter -- it controls how many labels are pre-computed and sent to the Flutter side.

Demo app

The root main.py is a comprehensive mobile-friendly demo with 7 sections covering all features: basic usage, styling, duration picker, disabled mode, programmatic updates, cross-slider control, and event logging.

Run it with flet build apk from the project root, or use python build.py for the full build+deploy pipeline.

Examples

Individual examples in examples/:

• basic.py -- Minimal slider with on_change event
• advanced.py -- Custom colors, geometry, labels, sizing, and all three events
• duration_picker.py -- Duration picker using label_formatter to display "1h 30m" style labels
• live_dashboard.py -- Full dashboard with auto-animation, controller slider, and colored presets
• feature_demo.py -- Disabled mode, text styling, and multi-color gradients

Properties

Events

e.data is a string. For integer divisions use int(e.data). For continuous (no divisions) or fractional ranges use float(e.data).

Repo structure

├── main.py                          # demo app (flet build target)
├── build.py                         # APK build+deploy automation
├── serve_web.py                     # local web server for flet build web
├── pyproject.toml                   # demo app config
├── flet_circular_slider/            # library (published to PyPI)
│   ├── pyproject.toml
│   └── src/
│       ├── flet_circular_slider/    # Python control
│       └── flutter/                 # Dart/Flutter widget
└── examples/                        # standalone examples

Building

Custom Flet extensions require flet build to compile Dart/Flutter code. flet run alone shows "Unknown control" because it uses a pre-built binary.

flet build web       # no extra tooling needed
flet build windows   # requires Visual Studio C++ workload
flet build apk       # Android
flet build macos     # macOS

After building, flet run works for Python-only changes. Rebuild when you change Dart code.

License

MIT