Skip to main content

​
Quick start

In this tutorial, you’ll build a working counter app to learn the fundamentals of Flet. By the end, you’ll understand how to create UI controls, handle events, and update your app in response to user actions.

​
What you’ll build

A simple counter application with:
  • A text field displaying the current count
  • Buttons to increment and decrement the value
  • Clean, centered layout
Counter app screenshot

​
Prerequisites

Before starting, make sure you have:
  • Flet installed on your system
  • A text editor or IDE
  • Basic Python knowledge

​
Create your first app

1

Create a new file

Create a new file called counter.py in your project directory.
2

Import Flet

Start by importing the Flet module:
import flet as ft
This gives you access to all Flet controls and functionality through the ft namespace.
3

Define the main function

Every Flet app starts with a main function that receives a Page object:
def main(page: ft.Page):
    page.title = "Flet counter example"
    page.vertical_alignment = ft.MainAxisAlignment.CENTER
The Page is the top-level container for your app. Here we set the window title and center the content vertically.
4

Create the counter control

Add a text field to display the counter value:
def main(page: ft.Page):
    page.title = "Flet counter example"
    page.vertical_alignment = ft.MainAxisAlignment.CENTER
    
    input = ft.TextField(value="0", text_align=ft.TextAlign.RIGHT, width=100)
The TextField starts at 0, aligns text to the right, and has a fixed width.
5

Add event handlers

Create functions to handle button clicks:
def main(page: ft.Page):
    page.title = "Flet counter example"
    page.vertical_alignment = ft.MainAxisAlignment.CENTER
    
    input = ft.TextField(value="0", text_align=ft.TextAlign.RIGHT, width=100)
    
    def minus_click(e):
        input.value = str(int(input.value) - 1)
        page.update()
    
    def plus_click(e):
        input.value = str(int(input.value) + 1)
        page.update()
These functions update the text field’s value and call page.update() to refresh the UI.
6

Build the layout

Create a row with the counter controls and add it to the page:
def main(page: ft.Page):
    page.title = "Flet counter example"
    page.vertical_alignment = ft.MainAxisAlignment.CENTER
    
    input = ft.TextField(value="0", text_align=ft.TextAlign.RIGHT, width=100)
    
    def minus_click(e):
        input.value = str(int(input.value) - 1)
        page.update()
    
    def plus_click(e):
        input.value = str(int(input.value) + 1)
        page.update()
    
    page.add(
        ft.Row(
            alignment=ft.MainAxisAlignment.CENTER,
            controls=[
                ft.IconButton(ft.Icons.REMOVE, on_click=minus_click),
                input,
                ft.IconButton(ft.Icons.ADD, on_click=plus_click),
            ],
        )
    )
The Row layout arranges the minus button, text field, and plus button horizontally.
7

Run the app

Finally, add the entry point to run your app:
ft.run(main)
Here’s the complete code:
import flet as ft

def main(page: ft.Page):
    page.title = "Flet counter example"
    page.vertical_alignment = ft.MainAxisAlignment.CENTER
    
    input = ft.TextField(value="0", text_align=ft.TextAlign.RIGHT, width=100)
    
    def minus_click(e):
        input.value = str(int(input.value) - 1)
        page.update()
    
    def plus_click(e):
        input.value = str(int(input.value) + 1)
        page.update()
    
    page.add(
        ft.Row(
            alignment=ft.MainAxisAlignment.CENTER,
            controls=[
                ft.IconButton(ft.Icons.REMOVE, on_click=minus_click),
                input,
                ft.IconButton(ft.Icons.ADD, on_click=plus_click),
            ],
        )
    )

ft.run(main)

​
Run your app

Launch your counter app from the terminal: 
flet run counter.py
The default flet run command opens your app in a native desktop window. Use the --web flag to run it in your browser instead.

​
Understanding the code

Let’s break down the key concepts:

​
Page object

The Page is the root container for your app. It represents the window (desktop) or browser tab (web) where your app runs. 
def main(page: ft.Page):
    page.title = "Flet counter example"  # Window title
    page.vertical_alignment = ft.MainAxisAlignment.CENTER  # Center content

​
Controls

Controls are the building blocks of your UI. In this app, we used:
  • TextField - Text input/display field
  • IconButton - Clickable button with an icon
  • Row - Layout that arranges controls horizontally
input = ft.TextField(value="0", text_align=ft.TextAlign.RIGHT, width=100)

​
Event handlers

Functions that respond to user interactions. Each handler receives an event object (usually named e): 
def minus_click(e):
    input.value = str(int(input.value) - 1)
    page.update()
Always call page.update() after modifying control properties to refresh the UI. Without this call, your changes won’t be visible to the user.

​
Layout controls

Layout controls like Row and Column help you organize other controls: 
ft.Row(
    alignment=ft.MainAxisAlignment.CENTER,  # Center horizontally
    controls=[button1, input, button2],  # Child controls
)

​
Experiment and learn

Try modifying the app to deepen your understanding:

Add a reset button

Create a button that sets the counter back to zero.

Change the increment

Make the buttons add/subtract by 5 or 10 instead of 1.

Add styling

Change colors, fonts, or sizes using control properties.

Display limits

Prevent the counter from going below 0 or above 100.

​
Common issues

​
UI doesn’t update

If your UI doesn’t reflect changes, make sure you’re calling page.update() after modifying control properties.

​
Import errors

If you see ModuleNotFoundError: No module named 'flet', ensure Flet is installed: 
pip install flet

​
App window doesn’t open

On Linux, you may need to install additional system packages. See the installation guide for details.

​
Next steps

You’ve built your first Flet app! Here’s what to explore next:

Controls reference

Learn about all available UI controls and their properties.

Layout guide

Master layouts with Row, Column, Stack, and GridView.

Todo app tutorial

Build a more complex app with data persistence and multiple views.

Browse examples

Explore sample apps showcasing different Flet features.

​
Get help

Need assistance? The Flet community is here to help:

Build docs developers (and LLMs) love

Get started for freeTalk to us