CTkKanBan 1.0.0

A configurable, database-ready Kanban board for CustomTkinter

CTkKanban

CTkKanban is a configurable Kanban widget for CustomTkinter desktop applications. It ships with a polished adaptive light/dark design, live inline card editing, generated forms, drag and drop, search, advanced filters, sorting, undo/redo, responsive columns, and database-backed operation.

The built-in design uses layered surfaces, priority-accented cards, responsive metadata tiles, column color rails, active filter treatments, and database status pills. Every visual token remains overridable through style or theme.

Install

python -m pip install CTkKanBan

In-memory board

import customtkinter as ctk
import CTkKanBan

board_class = CTkKanBan.CTkKanbanBoard

app = ctk.CTk()
board = board_class(
    app,
    columns=[{"id": "todo", "title": "To Do"}, {"id": "done", "title": "Done"}],
    cards=[{"id": 1, "column": "todo", "title": "Try CTkKanban"}],
    completed_columns=["done"],
)
board.pack(fill="both", expand=True)
app.mainloop()

Inline card editing

Inline editing is enabled by default. Click any value rendered on a card—including an empty show_on_card field—to edit it without opening a dialog. Press Enter or click the check button to save, click away to autosave, or press Escape to cancel. Text areas use Ctrl+Enter to save so Enter can still insert a new line.

Edits use the same validation, callbacks, undo history, filtering, sorting, and persistence path as update_card(). Read-only and hidden fields are never editable. To keep the earlier popup/side-panel interaction, configure enable_inline_card_editing=False; open_edit_card_form(card_id) also remains available for an explicit full-card form.

board = CTkKanbanBoard(
    app,
    columns=columns,
    cards=cards,
    fields=fields,
    enable_inline_card_editing=True,
)

# Keyboard-free or application-driven activation is also available.
board.start_inline_card_edit(card_id=1, field_key="priority")

Automatic field hit targets are available with the default card renderer. Applications using a custom card_renderer retain the full-card edit flow and can build their own editing controls.

SQLite board

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"}], [])

board = CTkKanbanBoard(
    app,
    data_source=source,
    board_id="work",
    auto_load=True,
    server_side_query=True,
    poll_interval_ms=2000,
)
board.pack(fill="both", expand=True)
app.mainloop()

Database work runs outside Tk's UI thread. Mutations carry event, transaction, actor, board, and expected-revision metadata. Adapters may return canonical records with generated IDs, timestamps, versions, and defaults. Failed network writes can be retried or held in the process-local offline queue until connectivity returns.

The built-in SQLite adapter provides transactional writes, optimistic revisions, atomic batches, server-side search/filter/sort, paging, change polling, generated IDs, and automatic timestamps. The board shows saving, saved, offline, conflict, and error states; duplicate submissions are blocked while a mutation is pending.

For an existing SQL, document, key-value, ORM, or API-backed repository, use CRUDKanbanDataSource instead of implementing the full adapter contract:

from ctk_kanban import CRUDKanbanDataSource

source = CRUDKanbanDataSource(
    read=repository.read_board,
    create=repository.create,
    update=repository.update,
    delete=repository.delete,
    transaction=repository.transaction,  # Optional
)

The four callbacks receive either "card" or "column", the board ID, the record or ID, and a CRUDContext. The bridge translates moves, reorders, renames, batching, paging, search, filters, and canonical generated IDs. This keeps database-specific connection and query code in your application.

Use only one durable writer: configure either data_source or the legacy on_data_changed callback, never both.

See the database integration guide for the adapter contract, event shape, conflict policies, paging, polling, and a production integration checklist.

The example programs are included in the source repository and source distribution, not the installed wheel. From a source checkout, run python example_all_features.py for the UI showcase or python example_sqlite.py for the transactional database example.

Use python example_all_features.py --light, --dark, or --form to inspect specific appearance and form states. Add --diagnose to print the exact package path and version being rendered.

Development

python -m pip install -e ".[dev]"
tox -e lint,type,py314,ctk-min,ctk-current,package

CI tests Python 3.10 through 3.14 on Linux and the oldest/latest supported versions on Windows and macOS. It also checks branch coverage, installed-wheel behavior, SQLite persistence, dependency vulnerabilities, package metadata, and workflow security.

See the changelog, contribution guide, publishing runbook, and project documentation.