Skip to content

Draggable

A control that can be dragged from to a DragTarget.

When a draggable control recognizes the start of a drag gesture, it displays the content_feedback control that tracks the user's finger across the screen. If the user lifts their finger while on top of a DragTarget, this target is given the opportunity to complete drag-and-drop flow.

Inherits: Control

Properties

  • affinity(Axis | None) –

    Specifies the axis along which this control competes with other gestures to

  • axis(Axis | None) –

    Restricts the draggable's movement to a specific axis.

  • content(Control) –

    The control to display when the draggable is not being dragged.

  • content_feedback(Control | None) –

    The control to show under the pointer when a drag is under way.

  • content_when_dragging(Control | None) –

    The control to display instead of content when this draggable

  • group(str) –

    The group this draggable belongs to.

  • max_simultaneous_drags(int | None) –

    Specifies how many simultaneous drag operations are allowed for this draggable.

Events

Examples#

Live example

Drag and drop Containers#

import flet as ft


def main(page: ft.Page):
    def handle_drag_will_accept(e: ft.DragWillAcceptEvent):
        e.control.content.border = ft.Border.all(
            2, ft.Colors.BLACK45 if e.accept else ft.Colors.RED
        )
        e.control.update()

    def handle_drag_accept(e: ft.DragTargetEvent):
        src = page.get_control(e.src_id)
        e.control.content.bgcolor = src.content.bgcolor
        e.control.content.border = None
        e.control.update()

    def handle_drag_leave(e: ft.DragTargetLeaveEvent):
        e.control.content.border = None
        e.control.update()

    page.add(
        ft.Row(
            controls=[
                ft.Column(
                    controls=[
                        ft.Draggable(
                            group="color",
                            content=ft.Container(
                                width=50,
                                height=50,
                                bgcolor=ft.Colors.CYAN,
                                border_radius=5,
                            ),
                            content_feedback=ft.Container(
                                width=20,
                                height=20,
                                bgcolor=ft.Colors.CYAN,
                                border_radius=3,
                            ),
                        ),
                        ft.Draggable(
                            group="color",
                            content=ft.Container(
                                width=50,
                                height=50,
                                bgcolor=ft.Colors.YELLOW,
                                border_radius=5,
                            ),
                        ),
                        ft.Draggable(
                            group="color",
                            content=ft.Container(
                                width=50,
                                height=50,
                                bgcolor=ft.Colors.GREEN,
                                border_radius=5,
                            ),
                        ),
                    ]
                ),
                ft.Container(width=100),
                ft.DragTarget(
                    group="color",
                    on_will_accept=handle_drag_will_accept,
                    on_accept=handle_drag_accept,
                    on_leave=handle_drag_leave,
                    content=ft.Container(
                        width=50,
                        height=50,
                        bgcolor=ft.Colors.BLUE_GREY_100,
                        border_radius=5,
                    ),
                ),
            ]
        )
    )


ft.run(main)

drag-and-drop-containers

Properties#

affinity class-attribute instance-attribute #

affinity: Axis | None = None

Specifies the axis along which this control competes with other gestures to initiate a drag.

  • If None, the drag starts as soon as a tap down gesture is recognized, regardless of direction.
  • If set to Axis.HORIZONTAL or Axis.VERTICAL, the control will only initiate a drag when the gesture matches the specified axis, allowing it to compete with other gestures in that direction.

axis class-attribute instance-attribute #

axis: Axis | None = None

Restricts the draggable's movement to a specific axis.

  • Axis.HORIZONTAL: Only allows horizontal dragging.
  • Axis.VERTICAL: Only allows vertical dragging.
  • None: Allows dragging in any direction.

content instance-attribute #

content: Control

The control to display when the draggable is not being dragged.

If the draggable is being dragged, the content_when_dragging is displayed instead.

Raises:

content_feedback class-attribute instance-attribute #

content_feedback: Control | None = None

The control to show under the pointer when a drag is under way.

content_when_dragging class-attribute instance-attribute #

content_when_dragging: Control | None = None

The control to display instead of content when this draggable is being dragged.

If set, this control visually replaces content during an active drag operation, allowing you to show a different appearance or an "empty" placeholder. If None, the original content remains visible while dragging.

group class-attribute instance-attribute #

group: str = 'default'

The group this draggable belongs to.

Note

For a DragTarget to accept an incoming drop from a Draggable, they must both be in the same group.

max_simultaneous_drags class-attribute instance-attribute #

max_simultaneous_drags: int | None = None

Specifies how many simultaneous drag operations are allowed for this draggable.

  • 0 - disables dragging entirely.
  • 1 - allows only one drag at a time. For a better user experience, you may want to provide an "empty" widget for content_when_dragging to visually indicate the item is being moved.
  • Set to any positive integer to allow that many concurrent drags.
  • If None, there is no limit on the number of simultaneous drags.

Raises:

Events#

on_drag_complete class-attribute instance-attribute #

on_drag_complete: ControlEventHandler[Draggable] | None = (
    None
)

Called when this draggable is dropped and accepted by a DragTarget.

on_drag_start class-attribute instance-attribute #

on_drag_start: ControlEventHandler[Draggable] | None = None

Called when this draggable starts being dragged.