CTkKanBan

Introduction

The package is built around one primary widget: CTkKanbanBoard. You give it an ordered set of columns, an optional initial set of cards, and an optional field schema. From there, the board handles rendering, selection, drag-and-drop movement, search, filters, sorting, inline field editing, built-in forms, and context menus.

Two design choices define the project:

• The board owns defensive copies of your column and card dictionaries. It never asks you to mutate UI state in place.
• Persistence is adapter-driven for database applications, with a legacy callback path for files and small local boards. The included SQLite adapter is transactional and operation-first.

Installation

The package metadata in pyproject.toml declares:

• requires-python = ">=3.10"
• dependencies = ["customtkinter>=5.2.2,<7", "tzdata ..."]

1. Create a virtual environment

python -m venv .venv

2. Activate it

# Windows PowerShell
.venv\Scripts\Activate.ps1

# macOS / Linux
source .venv/bin/activate

3. Install the package

python -m pip install CTkKanBan

Verify the interpreter and installed package before debugging GUI code:

python -c "import CTkKanBan; print(CTkKanBan.__version__, CTkKanBan.__file__)"

4. Explore the source examples (optional)

The examples are included in the source repository and source distribution, not the installed wheel. From a source checkout, install the checkout and run:

python -m pip install -e .
python example_all_features.py
python example_sqlite.py

The demo exercises custom fields, built-in forms, callbacks, styling, drag-and-drop, search, filtering, sorting, and a custom card renderer. example_sqlite.py is the runnable persistence example. Together they are the best source-level tour of intended application usage.

Quick Start

A minimal board needs three things:

1. An ordered list of columns.
2. An optional list of cards.
3. A CTk window that gives the board room to expand.

import customtkinter as ctk

from ctk_kanban import CTkKanbanBoard


columns = [
    {"id": "todo", "title": "To Do", "color": "#3B82F6"},
    {"id": "doing", "title": "Doing", "color": "#F59E0B"},
    {"id": "done", "title": "Done", "color": "#10B981"},
]

cards = [
    {"id": 1, "column": "todo", "title": "Write docs", "sort_order": 1},
    {"id": 2, "column": "doing", "title": "Review callbacks", "sort_order": 1},
]

app = ctk.CTk()
app.title("CTkKanBan Quick Start")
app.geometry("1100x700")
app.grid_rowconfigure(0, weight=1)
app.grid_columnconfigure(0, weight=1)

board = CTkKanbanBoard(app, columns=columns, cards=cards)
board.grid(row=0, column=0, sticky="nsew")

app.mainloop()

Choose a Storage Path

Start with the smallest persistence option that matches the application. You can change paths later because the board UI talks to storage through stable operation and result contracts.

Board Model

The board works with plain mappings rather than custom ORM or dataclass types. The typed definitions in ctk_kanban.models document the expected shapes, but at runtime the widget accepts dictionary-like mappings and normalizes them.

Columns

A column is an ordered board lane. The required keys are id and title. Column IDs must be hashable and unique. Optional keys let you control appearance and behavior per column:

Cards

A card must include id, column, and title. Any additional keys are preserved. The board uses sort_order only for manual ordering; all other values are application-defined card data.

Fields

Fields describe how card keys should behave in the default renderer, built-in form, search, filtering, and sorting. If you do not provide a field list, the package uses a default schema containing title, description, priority, assignee, due_date, and tags.

If you provide a custom field list and omit title, the validator inserts a default title field at the front because the board always requires it.

Data state vs. view state

get_data() returns only mutable board data: columns and cards. get_state() goes further and includes the current search query, active filters, sort settings, per-column sorts, and the selected card ID. Use set_data() when reloading from storage, and set_state() when you want to restore both data and the current board view.

Build Your First Board

The simplest practical workflow is to build a board from local data, then mutate it through the public API. This lets you prototype UI behavior before introducing persistence.

import customtkinter as ctk

from ctk_kanban import CTkKanbanBoard


app = ctk.CTk()
app.geometry("1200x760")
app.grid_rowconfigure(0, weight=1)
app.grid_columnconfigure(0, weight=1)

board = CTkKanbanBoard(
    app,
    columns=[
        {"id": "backlog", "title": "Backlog"},
        {"id": "todo", "title": "To Do"},
        {"id": "done", "title": "Done"},
    ],
    cards=[
        {"id": 1, "column": "backlog", "title": "Audit dark theme", "sort_order": 1},
        {"id": 2, "column": "todo", "title": "Write tutorial", "sort_order": 1},
    ],
)
board.grid(row=0, column=0, sticky="nsew")

# Programmatic updates
board.add_card({"id": 3, "column": "todo", "title": "Review API docs"})
board.move_card(1, "todo", 0)
board.update_card(2, {"title": "Write getting started guide"})

app.mainloop()

A few behavior details are worth knowing immediately:

• add_card() appends a new card to the end of its column when sort_order is omitted.
• move_card() and reorder_card() rewrite manual sort_order values so the column remains sequential.
• get_cards_by_column() returns the current display order, not the raw insertion order of the internal card mapping.

Inline Editing and Built-in Card Forms

The built-in form system is driven entirely by field definitions. If enable_builtin_card_form=True, the board can open the add form automatically from the toolbar and per-column add buttons. Existing cards use inline field editing by default.

Click any value in the default card renderer to edit it in place. Empty editable show_on_card fields receive an add placeholder. Enter, focus loss, or the check button saves; Escape cancels. Text areas use Ctrl+Enter to save. Set enable_inline_card_editing=False to retain the earlier full-card edit flow.

fields = [
    {
        "key": "title",
        "label": "Title",
        "type": "text",
        "required": True,
        "show_on_card": True,
        "show_in_form": True,
        "searchable": True,
        "sortable": True,
    },
    {
        "key": "priority",
        "label": "Priority",
        "type": "select",
        "options": ["Low", "Medium", "High"],
        "default": "Medium",
        "show_on_card": True,
        "show_in_form": True,
        "filterable": True,
        "sortable": True,
    },
    {
        "key": "description",
        "label": "Description",
        "type": "textarea",
        "show_on_card": True,
        "show_in_form": True,
        "searchable": True,
    },
]

board = CTkKanbanBoard(
    app,
    columns=[{"id": "todo", "title": "To Do"}],
    cards=[],
    fields=fields,
    card_form_mode="sidepanel",  # or "popup"
    enable_inline_card_editing=True,
    enable_builtin_card_form=True,
)

board.open_add_card_form("todo")

Search, Filter, and Sort

Search, filter, and sort behavior is field-aware. The board only exposes fields in the built-in UI if the field definitions opt into that behavior.

fields = [
    {"key": "title", "label": "Title", "type": "text", "required": True, "searchable": True, "sortable": True},
    {"key": "assignee", "label": "Assignee", "type": "select", "options": ["Maya", "Owen"], "filterable": True, "searchable": True},
    {"key": "priority", "label": "Priority", "type": "select", "options": ["Low", "Medium", "High"], "filterable": True, "sortable": True},
    {"key": "due_date", "label": "Due date", "type": "date", "filterable": True, "sortable": True},
]

board = CTkKanbanBoard(
    app,
    columns=columns,
    cards=cards,
    fields=fields,
    filter_mode="dim",  # or "hide"
)

board.search("Maya")
board.apply_filters({"priority": "High", "overdue_only": True})
board.sort_cards("due_date")
board.sort_cards("manual", reverse=True, column_id="review")

Search rules

• The query is case-insensitive.
• The board searches only fields marked searchable=True.
• If no fields are marked searchable, the board falls back to searching title and description.

Filter rules

• The built-in filter dialog generates exact-match filters from fields marked filterable=True.
• apply_filters() also accepts list/set filters and callable predicates.
• filter_mode="hide" removes non-matching cards from view.
• filter_mode="dim" keeps non-matching cards visible but visually de-emphasized.

Sort rules

• Allowed keys are manual, priority, due_date, created_date, updated_date, title, and any field marked sortable=True.
• manual uses sort_order.
• priority has a fixed ranking of Critical, High, Medium, then Low.
• Per-column sorting is available through sort_cards(..., column_id=...) when allow_column_sorting=True.

Database and Persistence

Database integration is operation-first. The board updates optimistically, sends a focused mutation to one background persistence worker, then merges canonical IDs, timestamps, versions, or defaults returned by storage. Choose one of the following integration levels.

SQLite: complete local persistence

The included adapter owns its schema and uses a fresh thread-safe connection for each operation. It provides transactions, atomic batches, optimistic revisions, idempotent event replay, generated card IDs, timestamps, server-side adapter querying, paging, and change polling.

import customtkinter as ctk

from ctk_kanban import CTkKanbanBoard, SQLiteKanbanDataSource


app = ctk.CTk()
source = SQLiteKanbanDataSource("kanban.db")
source.seed_board(
    "work",
    [
        {"id": "todo", "title": "To Do"},
        {"id": "done", "title": "Done"},
    ],
    cards=[],
    replace=False,
)

board = CTkKanbanBoard(
    app,
    data_source=source,
    board_id="work",
    actor_id="desktop-user-17",
    auto_load=True,
    server_side_query=True,
    page_size=100,
    poll_interval_ms=2000,
    completed_columns=["done"],
)
board.pack(fill="both", expand=True)
app.mainloop()

Bring your own CRUD

CRUDKanbanDataSource is database-neutral: it does not guess a connection string, driver, schema, query language, or authentication model. Your application keeps those decisions and supplies four normal repository callbacks. This works for PostgreSQL, MySQL, SQL Server, Oracle, MongoDB, DynamoDB, Redis, graph databases, cloud SDKs, ORMs, and remote APIs.

from contextlib import contextmanager

from ctk_kanban import CRUDKanbanDataSource


def read_board(board_id):
    return {
        "columns": repository.list_columns(board_id),
        "cards": repository.list_cards(board_id),
        "revision": repository.get_revision(board_id),  # Optional
    }


def create(resource, board_id, record, context):
    # resource is exactly "card" or "column".
    return repository.insert(
        resource,
        board_id,
        record,
        position=context.position,
        transaction=context.transaction,
        event_id=context.metadata.event_id,
    )


def update(resource, board_id, record_id, record, context):
    return repository.update(
        resource,
        board_id,
        record_id,
        record,
        position=context.position,
        transaction=context.transaction,
        expected_revision=context.metadata.expected_revision,
    )


def delete(resource, board_id, record_id, context):
    repository.delete(
        resource,
        board_id,
        record_id,
        transaction=context.transaction,
    )


@contextmanager
def transaction(events):
    with repository.begin() as session:
        yield session


source = CRUDKanbanDataSource(
    read=read_board,
    create=create,
    update=update,
    delete=delete,
    transaction=transaction,  # Optional but recommended for atomic batches
)

The bridge translates board operations into CRUD calls:

• Card creates, updates, and deletes map directly to the corresponding callback.
• Card moves and reorders become focused card updates.
• Column order is supplied as context.position.
• Column ID changes also update affected card records.
• Generated IDs are remapped when create returns the canonical stored record.
• Search, filters, sorting, paging, and totals run over the result of read_board.
• A batch shares the object yielded by transaction(events).

CRUD callback return values

Implement the full data-source protocol

Use a direct adapter when reading every record into the CRUD bridge would be inefficient or when the backend should own concurrency, queries, event history, and batching.

from ctk_kanban import (
    BoardLoadResult,
    CardPage,
    CardQuery,
    ChangePage,
    MutationEvent,
    MutationResult,
)


class MyDataSource:
    def load_board(
        self, board_id: str, query: CardQuery | None = None
    ) -> BoardLoadResult:
        ...

    def apply_mutation(self, event: MutationEvent) -> MutationResult:
        ...

    def apply_batch(self, events: list[MutationEvent]) -> MutationResult:
        ...

    def query_cards(self, board_id: str, query: CardQuery) -> CardPage:
        ...

    def get_changes(
        self, board_id: str, since_revision: int | str | None
    ) -> ChangePage:
        ...

Adapter methods are intentionally blocking and thread-safe; PersistenceCoordinator owns the worker. Treat event_id as an idempotency key, check expected_revision in the same transaction as the write, and make apply_batch() all-or-nothing.

Mutation lifecycle and canonical records

1. Optimistic UI: the board validates and applies the local operation immediately.
2. Focused event: only affected records and trace metadata are submitted.
3. Background write: one worker preserves mutation order away from Tk.
4. Canonical merge: returned IDs, timestamps, versions, defaults, and affected records replace local values.
5. Failure recovery: rejection restores the prior board state; transient failures retry and may queue offline.

Retries, offline queue, and status

RetryPolicy defaults to three attempts with bounded exponential backoff. Connection, timeout, and operating-system failures move the coordinator offline after retries. Pending operations remain visible and queue in memory in FIFO order.

A custom adapter should raise ConnectionError, TimeoutError, or OSError for retryable connectivity failures. Domain rejections should return MutationResult(accepted=False, reason=...) instead.

Observe transitions with on_persistence_status or get_persistence_status(). Call set_online(True) after connectivity returns, or call retry_last_save() after resolving a rejected write.

Optimistic conflicts

Storage can return ConflictDetails when expected_revision is stale. Configure conflict_strategy as:

• "server_wins": replace local data with the server snapshot.
• "local_wins": retry the local operation against the current server revision.
• "callback": invoke on_conflict so the application decides.

Loading, querying, paging, and polling

• auto_load=True loads board_id after the widget is constructed.
• server_side_query=True delegates toolbar search, filters, sorting, and paging.
• page_size controls the requested page size; load_next_page() appends more.
• poll_interval_ms > 0 calls get_changes() and reloads after remote events.
• For push systems, call refresh_from_source() from the notification handler.

Legacy snapshot callback

on_data_changed remains useful for JSON files and small local snapshots. It runs synchronously and receives all columns and cards plus the focused action event.

def save_snapshot(event):
    write_json({"columns": event["columns"], "cards": event["cards"]})
    return True


board = CTkKanbanBoard(
    app,
    columns=columns,
    cards=cards,
    on_data_changed=save_snapshot,
)

Return False or {"cancel": True, "reason": "..."} to reject and restore an action. Use on_action_cancelled to display or log the reason.

Production checklist

• Keep credentials and authorization in the application database layer.
• Use stable string or integer IDs across JSON and database boundaries.
• Return generated IDs, defaults, UTC timestamps, and record versions from writes.
• Make event IDs idempotent and enforce expected revisions transactionally.
• Provide a transaction callback for multi-record CRUD operations.
• Test disconnect, retry, conflict, duplicate submission, and remote-change paths.
• Call destroy() when disposing the board so pending Tk callbacks and the worker close.

The standalone database integration guide contains the same persistence model in a compact format for teams that want a database-only handout.

Custom Rendering and Theme

The default renderer uses a modern adaptive light/dark system: layered board surfaces, colored column rails, priority-accented cards, compact metadata tiles, filter chips, persistence status pills, and matching form controls. These defaults work without a custom style and remain fully configurable.

The default card renderer is field-driven, but you can fully replace card content with a custom renderer while still using the built-in search, form, filter, and callback infrastructure.

import customtkinter as ctk


def render_card(card_frame, card_data, fields, theme):
    card_frame.grid_columnconfigure(0, weight=1)

    ctk.CTkLabel(
        card_frame,
        text=card_data["title"],
        anchor="w",
        font=ctk.CTkFont(size=14, weight="bold"),
        text_color=theme["text_color"],
    ).grid(row=0, column=0, sticky="ew", padx=10, pady=(10, 4))

    if card_data.get("description"):
        ctk.CTkLabel(
            card_frame,
            text=str(card_data["description"]),
            anchor="w",
            justify="left",
            wraplength=230,
            text_color=theme["muted_text_color"],
        ).grid(row=1, column=0, sticky="ew", padx=10, pady=(0, 10))


style = {
    "board_fg_color": ("#EEF2F7", "#09111F"),
    "column_fg_color": ("#E2E8F0", "#152033"),
    "card_fg_color": ("#FFFFFF", "#101827"),
    "card_hover_color": ("#F8FAFC", "#17233A"),
    "card_selected_color": ("#DBEAFE", "#1E3A5F"),
    "drop_indicator_color": "#38BDF8",
}

board = CTkKanbanBoard(
    app,
    columns=columns,
    cards=cards,
    fields=fields,
    style=style,
    priority_colors={"Critical": "#B91C1C"},
    tag_colors={"API": "#1D4ED8"},
    card_renderer=render_card,
)

The renderer signature is:

The first argument is the card frame that you populate. The board does not add default content when a custom renderer is supplied.

Drag and Reorder

The board supports both card dragging and column dragging. These features are enabled by default and are controlled by constructor flags rather than a separate drag manager.

• enable_card_drag toggles card movement.
• enable_card_reorder allows reordering inside a column.
• enable_column_drag allows dragging column headers.
• enable_drag_preview shows a drag preview window during movement.
• show_drop_indicator displays insertion markers.
• enable_horizontal_autoscroll and enable_vertical_autoscroll keep drag targets reachable near the edges.

Two column-level rules affect dragging:

• A locked column cannot receive moved cards.
• If enforce_column_limits=True, a column with max_cards set refuses additional cards once the limit is reached.

Selection, Menus, and Forms

CTkKanBan keeps a single selected card ID. Programmatic selection is exposed through select_card(), clear_selection(), and get_selected_card().

The built-in card context menu includes:

• Open: starts inline title editing by default.
• Edit: starts inline title editing directly.
• Delete: optionally confirms, then deletes.
• Duplicate: copies the card and appends (copy) to the title.
• Move to: lists eligible target columns.

You can append your own actions with card_context_menu_items. Each custom menu item can be always enabled, always disabled, or conditionally enabled with a callable.

State Snapshots and Bulk Loading

The board exposes a small but useful state API for serialization, persistence, and undo-like workflows.

This split is deliberate. Use get_data() for persistence formats that should not include UI search/filter state. Use get_state() for restoring the board as the user left it.

Undo and redo

End-user mutations record defensive before/after snapshots up to undo_limit. undo() and redo() restore those snapshots; with a data source attached, the board computes focused delta events so partially loaded server data is not overwritten.

Atomic application batches

Use apply_batch() for imports and multi-step edits. Supported operation names are add_card, update_card, delete_card, move_card, add_column, update_column, delete_column, and move_column.

saved = board.apply_batch(
    [
        {
            "operation": "update_card",
            "card_id": 10,
            "new_data": {"priority": "High"},
        },
        {
            "operation": "move_card",
            "card_id": 10,
            "target_column": "review",
        },
        {
            "operation": "add_card",
            "card_data": {
                "column": "todo",
                "title": "Follow up",
            },
        },
    ],
    source="bulk_edit",
)

Styling Surface

The board has a broad, flat style dictionary. Colors can be passed directly through theme or style, and the constructor merges nested priority_colors, tag_colors, and font_config overrides from the style mapping.

Visual details such as card_metadata_fg_color, card_accent_width, column_control_fg_color, column_count_full_fg_color, filter_chip_fg_color, and the success, warning, and danger surface colors can be changed independently. Existing broad keys such as card_fg_color and button_fg_color continue to work.

In practice:

• style overrides theme when both set the same style key.
• A font_config entry such as {"toolbar": font} becomes toolbar_font internally.
• get_style() returns the full merged style snapshot.

Constructor

Primary entry point:

The tables below cover the complete constructor surface for this release. Run help(CTkKanbanBoard) against your installed version when you need its exact live signature.

Common core data and layout parameters

Toolbar parameters

Column, card, and drag parameters

Search, filter, sort, and extension parameters

Responsive layout and card presentation

Data source, reliability, IDs, history, and localization

Callback parameters

Callbacks receive an event mapping. Mutation callbacks may cancel before persistence; status and conflict callbacks observe the asynchronous data-source lifecycle.

Board Methods

Mutation methods

Query and bulk-state methods

History, data-source, sizing, and lifecycle methods

View and UI methods

Persistence API

These public exports form the database-neutral boundary. Application code usually constructs one data source and passes it to CTkKanbanBoard; adapter authors use the typed contracts directly.

Data-source classes

CRUDKanbanDataSource

CRUDContext

SQLiteKanbanDataSource

Mutation contracts

Query and page contracts

RetryPolicy defaults

Data Types

ColumnDefinition

CardDefinition

FieldDefinition

Built-in field behavior by type

ContextMenuItem and related aliases

Callback Reference

Every event dictionary created by the board includes type, timestamp, and source. The rest of the payload depends on the callback.

Cancellation contract

Cancellable callbacks may reject an operation by returning False or a mapping with {"cancel": True}. Non-cancellable callbacks are purely observational.

Custom context menu callbacks

A ContextMenuItem.callback receives a single event with type="card_context_action", source="context_menu", card_id, and card_data.

Theme and Style Reference

The package exports DEFAULT_THEME, DEFAULT_STYLE, DEFAULT_PRIORITY_COLORS, merge_theme(), and merge_style(). The following keys exist in DEFAULT_THEME.

Board, toolbar, and column keys

Card and badge keys

Buttons, inputs, dialogs, menus, and utility keys

Font slots

The constructor accepts a font_config mapping. Each entry is stored internally as {name}_font. The current widgets read these font slots:

Lower-Level Widgets

Most applications only instantiate CTkKanbanBoard. The package also exports lower-level widgets that the board itself uses. These are most useful when you want to extend or embed parts of the board behavior in a custom composition.

Advanced dialog classes

Helper Modules

These functions are available from submodules and are useful when you want to integrate more tightly with the package's data model or UI helpers.

ctk_kanban.themes

ctk_kanban.events

ctk_kanban.validators

ctk_kanban.utils

Exceptions

FAQ and Troubleshooting

Why is a card not visible even though it exists?

Check the current search query, active filters, and filter_mode. In "hide" mode, non-matching cards are removed from the visible column contents. In "dim" mode they remain visible but muted.

Why did add_card() or update_card() return None?

A cancellable callback rejected the change. Check on_card_created, on_card_updated, or on_data_changed, and listen to on_action_cancelled for the reason.

Why did delete_card(), move_card(), or move_column() return False?

The operation was cancelled by a callback or, for delete, the user rejected a confirmation prompt.

Why can't I delete a column?

The public API only allows deleting empty columns. Move or delete the column's cards first.

Why does the overdue filter not match anything?

The built-in overdue check reads the configured due-date and completion fields. Completed columns and the display timezone are configurable, and database timestamps can be rendered for the chosen locale.

How do I add my own database layer?

Wrap your repository's four CRUD functions with CRUDKanbanDataSource. Implement KanbanDataSource directly only when you need native server-side queries, bulk writes, conflict snapshots, or change streams. Start at Database and Persistence.

Why is the board stuck on offline or error?

Inspect get_persistence_status() and your application logs. Transient connection failures retry and then queue offline; call set_online(True) when connectivity returns. Rejected writes and conflicts require resolution before retry_last_save().

Why does polling reload the board?

get_changes() reports that durable state advanced, then the board calls refresh_from_source() to obtain a consistent page. Set poll_interval_ms=0 to disable polling or call refresh from your own push notification handler.

Why did a generated database ID not appear?

Return the complete canonical stored card from a CRUD create callback, or set MutationResult.card/id_map in a custom adapter. The board will replace its temporary ID and update selection and widgets.

Can callbacks touch Tk widgets?

UI callbacks run on Tk's thread, but data-source and CRUD methods run on the persistence worker. Keep Tk access out of storage code; return typed results and let the coordinator schedule board updates.

Notes and Limitations

• The package includes a transactional SQLite adapter and a database-agnostic CRUD callback bridge. Advanced integrations can implement the KanbanDataSource protocol directly.
• The CRUD bridge filters and pages the complete read result in the worker. For very large datasets, implement native query_cards() in a full data source.
• The retry/offline queue is in memory, not a durable application outbox.
• The built-in UI does not provide a column creation, edit, or delete dialog. Column structure changes are available through the API, not a dedicated editor.
• Multiselect values use comma-separated entry. Date fields use the built-in calendar picker.
• Database adapters may populate canonical created_at, updated_at, and version fields. Legacy created_date and updated_date sort keys remain available for existing schemas.
• The internal filter matcher accepts both column and status as aliases for the card's current column ID, but the built-in filter UI generates only the fields marked filterable=True plus overdue_only.
• Card and column IDs must be hashable. Floating-point IDs must also be finite.
• Prefer stable string or integer IDs when board data crosses a JSON or database boundary.
• The built-in SQLite adapter requires non-empty string or integer card and column IDs so their types survive JSON storage. In-memory boards accept any valid hashable ID.