CTkKanban

CTkKanban is a small Kanban widget for CustomTkinter. It focuses on predictable card editing and movement instead of trying to be a database framework or a complete project-management application.

It provides:

• a CTkKanbanBoard widget with explicit editing, search, selection, menus, handle-only dragging, loading states, and light/dark theme support;
• a schema-driven editor for any number of typed card fields;
• granular action permissions, layout configuration, and customizable text;
• a Tk-free BoardModel with validation and deterministic manual ordering;
• detached snapshots, database-row adapters, and one application-owned change boundary for persistence.

The complete single-page guide is also available in docs/index.html. This README covers the same contracts in a format suited to package and repository viewers.

Contents

• Install
• Quick start
• Interaction model
• Styling and theme tokens
• Configuration and permissions
• Configurable card fields
• Data contract and ordering
• Change events and persistence
• Database rows
• Asynchronous loading
• API reference
• Errors and lifecycle
• Migrating from 1.x
• Development

Install

python -m pip install CTkKanBan

CTkKanban requires Python 3.10 or newer and installs CustomTkinter 5.2.2 or newer (below major version 7). CTkKanBan is the PyPI distribution name; ctk_kanban is the lowercase Python package name.

Quick start

Import the package with its canonical lowercase name:

import customtkinter as ctk

from ctk_kanban import CTkKanbanBoard

app = ctk.CTk()
app.geometry("1000x650")

board = CTkKanbanBoard(
    app,
    columns=[
        {"id": "todo", "title": "To do"},
        {"id": "doing", "title": "Doing"},
        {"id": "done", "title": "Done"},
    ],
    cards=[
        {
            "id": 1,
            "column": "todo",
            "title": "Try the simplified board",
            "description": "Click for details and use the handle to drag.",
            "priority": "High",
            "tags": ["demo"],
        }
    ],
    on_change=lambda event: print(event["type"], event["data"]),
)
board.pack(fill="both", expand=True)
app.mainloop()

columns and cards may be any iterables of mappings. Their input order is the initial manual order. Call board.get_data() at any time to retrieve the complete, detached state.

Interaction model

• Click a card to select it and open the editor drawer.
• Save explicitly with Save changes or Enter; Escape cancels.
• Drag cards only from their upper-right drag handle.
• Use the visible menu for move and delete actions.
• Columns use menu actions for left/right movement instead of column dragging.

There is no inline editing, click-away autosave, whole-card dragging, floating drag preview, or window-wide drag binding. A local Tk grab makes sure a handle drag always receives its release event.

The drawer marks changed state and disables Save until a value differs. Enter saves from ordinary controls, Ctrl+Enter saves from anywhere in the drawer, and Escape cancels. Enter inside a multiline textbox inserts a new line. Opening another editor replaces the currently open drawer.

Search is a case-insensitive substring match across only fields marked searchable; lists contribute each item. Search changes visibility, not data. Dragging and menu up/down ordering are disabled while results are filtered, because a visible index is ambiguous relative to hidden cards. Clear the query before interactive reordering.

Styling and theme tokens

Board surfaces, controls, text, hover states, and scrollbars follow the active CustomTkinter color theme. Call ctk.set_default_color_theme(...) before creating the board to use another built-in or custom theme. Priority and tag metadata remain visible as compact colored pills. The optional theme mapping can override individual board tokens when needed. DEFAULT_THEME contains the complete supported token set and unknown keys are rejected to catch spelling mistakes.

Themes now cover colors as well as component radii, borders, spacing, control heights, scrollbar width, compact-card limits, animation timing, and font definitions:

board = CTkKanbanBoard(
    app,
    columns=columns,
    cards=cards,
    theme={
        "card_corner_radius": 16,
        "card_title_font": {"size": 15, "weight": "bold"},
        "card_description_max_chars": 220,
        "column_gap": 10,
        "editor_section_corner_radius": 14,
    },
)

Visual choices belong in theme; behavior, layout, and user-facing labels belong in config.

Call merge_theme(overrides) when a reusable, validated mapping is useful. It reads fresh defaults from the active CustomTkinter theme, deep-copies the overrides where possible, and rejects unknown token names. DEFAULT_THEME is the import-time discovery snapshot. A color may be a normal CustomTkinter color string or a (light, dark) pair. Font tokens are keyword mappings passed to ctk.CTkFont. Palette tokens such as column_accent_colors and tag_pill_colors must remain non-empty sequences.

Complete token reference

The supported token set is intentionally closed. Values are shown through DEFAULT_THEME; the table below describes all 97 names.

Theme mappings are resolved at construction time. Changing the source mapping later does not restyle existing child widgets; create or rebuild the board when switching to a substantially different per-board theme.

Configuration and permissions

config accepts a BoardConfig instance or a nested mapping. It separates available actions, major layout choices, labels, and delete confirmation:

board = CTkKanbanBoard(
    app,
    columns=columns,
    cards=cards,
    config={
        "actions": {
            "delete_cards": False,
            "delete_columns": False,
            "move_columns": False,
        },
        "layout": {
            "show_toolbar": True,
            "column_width": 340,
            "column_height": 560,
            "editor_width": 480,
        },
        "text": {
            "board_title": "Release planning",
            "add_card": "+ New work item",
        },
        "confirm_delete": True,
    },
)

The same configuration can be constructed with frozen dataclasses:

from ctk_kanban import ActionConfig, BoardConfig, LayoutConfig, TextConfig

config = BoardConfig(
    actions=ActionConfig(delete_cards=False, delete_columns=False),
    layout=LayoutConfig(column_width=340, column_height=560),
    text=TextConfig(board_title="Release planning"),
    confirm_delete=True,
)

Nested mappings may be partial; omitted values retain the defaults. Unknown keys are rejected. merge_config(config) validates either representation and returns a BoardConfig.

Action settings

All action settings default to True.

Disabled public mutation methods raise BoardModelError. UI-opening helpers return without opening when their action is disabled. These settings do not block set_data(), set_fields(), or direct access to board.model; they are widget behavior controls, not a security boundary. BoardModel deliberately has no action configuration.

When card deletion is disabled, delete_column(..., delete_cards=True) is also blocked for non-empty columns. This prevents column deletion from bypassing the card policy. confirm_delete only controls confirmation dialogs started by the built-in menus; direct API deletions never prompt.

Layout settings

Text settings

Every text setting must be a string. These are the stable application-facing labels; short mechanical labels inside the editor and context menus are not currently configurable.

For the common deletion-only case, the convenience arguments are equivalent:

board = CTkKanbanBoard(
    app,
    columns=columns,
    cards=cards,
    allow_card_deletion=False,
    allow_column_deletion=False,
)

Existing direct options such as show_toolbar, enable_drag, column_width, column_height, editor_width, confirm_delete, and board_title override the corresponding structured setting when explicitly supplied. The two allow_*_deletion arguments override actions.delete_cards and actions.delete_columns. Remaining keyword arguments are forwarded to the outer CTkFrame after the board supplies its default fg_color.

Configurable card fields

Pass fields to define any number of typed card values. The built-in editor is generated from these definitions, card rendering uses their display roles, and search uses fields marked searchable. When fields is omitted, the existing title, description, priority, and tags behavior remains unchanged.

fields = [
    {
        "key": "title",
        "label": "Title",
        "type": "text",
        "required": True,
        "show_on_card": True,
        "searchable": True,
        "card_role": "title",
        "section": "Details",
    },
    {
        "key": "client",
        "label": "Client",
        "type": "text",
        "show_on_card": True,
        "searchable": True,
        "card_role": "metadata",
        "section": "Details",
    },
    {
        "key": "estimate",
        "label": "Estimate",
        "type": "integer",
        "min": 0,
        "max": 100,
        "show_on_card": True,
        "card_role": "metadata",
        "section": "Planning",
    },
    {
        "key": "blocked",
        "label": "Blocked",
        "type": "checkbox",
        "section": "Planning",
    },
    {
        "key": "stage",
        "label": "Stage",
        "type": "select",
        "options": ["Discovery", "Delivery", "Review"],
        "show_on_card": True,
        "card_role": "badge",
        "colors": {
            "Discovery": ("#DBEAFE", "#1E3A5F"),
            "Delivery": ("#DCFCE7", "#14532D"),
        },
    },
    {
        "key": "due_date",
        "label": "Due date",
        "type": "date",
        "show_on_card": True,
        "card_role": "metadata",
    },
]

cards = [
    {
        "id": 1,
        "column": "todo",
        "title": "Prepare proposal",
        "client": "Acme",
        "estimate": 8,
        "blocked": False,
        "stage": "Delivery",
        "due_date": "2026-08-28",
    }
]

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

Field types and stored values

Date and date-time controls are plain text entries, so validation occurs on save. multiselect uses the same compact add/remove interaction as tags; invalid choices are reported when the schema validates the completed card.

Field definition reference

Every definition requires a unique, nonblank key and label.

Unknown definition options are rejected so spelling mistakes cannot silently change behavior. min must not exceed max, length limits must be nonnegative, and the lower length limit must not exceed the upper one. Validators run in field order and should be fast and side-effect free because they also run during load and schema replacement.

def estimate_validator(value, card):
    if value is not None and card.get("blocked") and value > 8:
        return "Blocked work must be split into estimates of 8 or less"
    return True


fields = [
    {"key": "title", "label": "Title", "required": True},
    {"key": "blocked", "label": "Blocked", "type": "checkbox"},
    {
        "key": "estimate",
        "label": "Estimate",
        "type": "integer",
        "validator": estimate_validator,
        "formatter": lambda value, _card: "" if value is None else f"{value} pts",
        "show_on_card": True,
        "card_role": "metadata",
    },
]

Compact-card roles

Only fields with show_on_card=True render, regardless of role. Empty values are omitted. formatter changes display text but never the normalized stored value. A field's colors mapping takes precedence for its exact value; the default priority field otherwise uses the priority theme colors.

id, column, and column_id are reserved structural keys. If title is not supplied in fields, the default title definition is inserted. The title must use text or textarea, is forced to required=True and show_on_card=True, and must be the only field with card_role="title".

Additional card keys that are not in the schema are deep-copied and preserved in snapshots. This lets applications round-trip private integration metadata without showing, validating, formatting, or searching it. Add a definition whenever the board should understand such a value.

Use get_fields() to inspect the active definitions and set_fields(fields) to replace them at runtime. set_fields() validates existing cards atomically, rebuilds their compact views, and rebuilds an open editor with the new controls. If schema normalization changes stored card values, one fields_changed event is emitted so the host can persist the new snapshot.

get_fields() returns a detached copy. Mutating that copy has no effect until it is passed back to set_fields(). A failed replacement leaves both the old schema and every card unchanged. Changing a schema can add defaults, coerce values, or reject existing data; plan schema migrations the same way you would plan a database migration.

Data contract and ordering

A snapshot is exactly one mapping with columns and cards keys:

snapshot = {
    "columns": [
        {"id": "todo", "title": "To do"},
        {"id": "done", "title": "Done"},
    ],
    "cards": [
        {"id": 1, "column": "todo", "title": "Write docs"},
    ],
}

Extra top-level snapshot keys and extra column keys are rejected. A column has only id and title; titles are trimmed and must remain nonblank. A card must have id, a column reference, and a nonblank title. Input may use column_id as an alias for column; output always uses column. Supplying both aliases with different values is an error.

IDs must be unique within their record kind and must be a nonblank str or an int; booleans, floats, None, and other objects are rejected. IDs are not coerced, so 1 and "1" are distinct. Use only strings or integers when serializing to JSON and keep the same type in related card/column values.

With the default field schema, cards normalize title, description, priority, and tags. Priority is case-sensitive and must be empty, Low, Medium, High, or Critical. A custom schema controls its configured keys; all other card keys are preserved as application metadata.

Snapshots, copies, and atomic replacement

get_data() and BoardModel.snapshot() return deep, detached state. The record getters and returned mutation records are detached too, so changing them never mutates the live board. Call a mutation method or set_data() to apply a change.

set_data(snapshot) validates the entire replacement before changing the model and redraws without emitting on_change. Invalid replacement data leaves the old board intact. The snapshot shape must be complete; use empty lists to clear a board. BoardModel.load() additionally supports the explicit form load(columns=..., cards=...), but snapshot and explicit arguments cannot be mixed.

Manual ordering

Column input order is retained. Card order is retained within each column and global get_cards() output is grouped by current column order. index values are zero-based insertion positions; None appends. Valid insertion positions range from zero through the destination size, inclusive. An out-of-range or non-integer index raises BoardModelError.

update_card() merges its mapping into the existing record; it does not replace unspecified values. A changed column appends the card to that column, while move_card() accepts an exact insertion index. update_column() only accepts title. Non-empty columns require the explicit delete_cards=True cascade flag before deletion.

Change events and persistence

Pass one on_change(event) callback to observe successful board mutations. Every event contains a detached before snapshot, the current complete data snapshot, its type, and the operation payload:

No event is emitted for a no-op update or move, set_data(), a schema change that leaves card data identical, search, selection, rendering, or loading-state changes. The board state has already changed when the callback runs. Callback exceptions are logged and do not roll back the mutation.

def persist(event):
    try:
        repository.save_snapshot(event["data"])
    except Exception:
        # Optional application policy: restore the last detached state.
        board.set_data(event["before"])
        raise


board = CTkKanbanBoard(app, columns=columns, cards=cards, on_change=persist)

on_change runs on Tk's UI thread, so synchronous network or database work will freeze the interface. For nontrivial persistence, enqueue event["data"] to an application worker and decide how your application handles failures, retries, coalescing, optimistic concurrency, and conflicts. CTkKanban does not save, poll, page, retry, or resolve conflicts itself.

Database rows

Database results can be converted without adding a database-driver dependency to CTkKanban. Mapping rows from psycopg dict_row, sqlite3.Row, and SQLAlchemy are accepted by snapshot_from_rows():

from ctk_kanban import snapshot_from_rows

snapshot = snapshot_from_rows(column_rows, card_rows, fields=fields)
board.set_data(snapshot)

Plain DB-API tuple results can be converted using cursor metadata. Fetch each result before reusing its cursor:

from ctk_kanban import rows_from_cursor, snapshot_from_rows

cursor.execute("SELECT id, title FROM kanban_columns ORDER BY position")
columns = rows_from_cursor(cursor)

cursor.execute(
    """
    SELECT id, column_id AS column, title, description, priority, tags
    FROM kanban_cards
    ORDER BY column_id, position
    """
)
cards = rows_from_cursor(cursor)

board.set_data(snapshot_from_rows(columns, cards))

Use SQL aliases such as column_id AS column to produce CTkKanban's exact record keys. Result column names must be unique. rows_from_cursor() consumes all remaining rows returned by the cursor.

snapshot_from_cursors(columns_cursor, cards_cursor) is a shorter equivalent when two separately executed cursors are available. Every snapshot helper normalizes and validates the complete result before returning it.

Pass the same fields used by the board so database values receive identical normalization. SQL drivers may return JSON/array values in driver-specific forms; convert them to the expected Python list, boolean, number, or string in the query/repository layer when necessary. Neither adapter executes SQL, commits, closes a cursor, nor owns a connection.

Asynchronous loading

load_async() performs fetching and validation on a daemon worker, then calls set_data() and user callbacks safely on Tk's thread:

import psycopg
from psycopg.rows import dict_row

from ctk_kanban import snapshot_from_rows


def fetch_board():
    with psycopg.connect(DATABASE_URL, row_factory=dict_row) as connection:
        columns = connection.execute(COLUMN_QUERY).fetchall()
        cards = connection.execute(CARD_QUERY).fetchall()
        return snapshot_from_rows(columns, cards)


board.load_async(
    fetch_board,
    on_success=lambda snapshot: print("Loaded", len(snapshot["cards"]), "cards"),
    on_error=lambda error: print("Load failed:", error),
)

board.is_loading reports pending work and board.load_error retains the most recent asynchronous error. Existing data is preserved on failure unless clear_on_error=True is requested. Starting a newer load makes an older result stale, so it cannot overwrite newer data.

load_async() returns the started daemon threading.Thread. The fetch callable receives no arguments and must return a complete snapshot mapping. It runs off-thread and must not read or update Tk widgets. Validation uses the board field schema; application of the validated snapshot plus on_success or on_error happens on Tk's event loop. Successful loads use set_data() and therefore do not emit on_change.

At the start of a load, load_error is cleared and is_loading becomes true. On failure, the original exception is stored and passed to on_error; with clear_on_error=True, the board is replaced with empty lists first. A newer load invalidates delivery from older workers but does not forcibly stop their Python threads. Destroying the board invalidates pending delivery, and starting a load after destruction raises RuntimeError.

set_loading(True) is also public for application-owned tasks. It changes the toolbar presentation and disables its search/add controls; it does not start a worker, block public mutations, or alter data.

Pass on_card_open when the host application owns card editing. Its callback receives the card snapshot and replaces the built-in drawer when a card opens.

API reference

CTkKanbanBoard constructor

CTkKanbanBoard(
    master,
    columns=(),
    cards=(),
    *,
    on_change=None,
    on_card_open=None,
    theme=None,
    fields=None,
    config=None,
    show_toolbar=None,
    enable_drag=None,
    column_width=None,
    column_height=None,
    editor_width=None,
    confirm_delete=None,
    allow_card_deletion=None,
    allow_column_deletion=None,
    board_title=None,
    **kwargs,
)

master is the parent Tk widget. columns and cards provide initial state; all other inputs are keyword-only. theme, fields, and config use the contracts above. on_change receives event dictionaries, and on_card_open receives a detached card record in place of the built-in existing-card editor. Direct layout/text/deletion options take precedence over structured config.

Board data, view, and schema methods

Board mutation methods

Each board mutation enforces its action setting and emits the corresponding event only when data changes.

Board editor and loading methods

BoardModel

The Tk-free BoardModel(columns=(), cards=(), *, fields=None) is useful in repositories, tests, command-line tools, and preprocessing layers. It supplies:

snapshot()
load(data=None, *, columns=None, cards=None)
get_card(card_id) / get_cards(column_id=None) / get_columns()
get_fields() / set_fields(fields)
add_card(card, *, index=None)
update_card(card_id, updates=None, **changes)
delete_card(card_id)
move_card(card_id, column_id, index=None)
reorder_card(card_id, index)
add_column(column, *, index=None)
update_column(column_id, updates=None, **changes)
delete_column(column_id, *, delete_cards=False)
move_column(column_id, index)
clear()

Unlike the widget's forgiving get_card(), BoardModel.get_card() raises BoardModelError for an invalid or unknown ID. The model does not enforce BoardConfig permissions or emit events. Its update_card() and update_column() accept keyword changes in addition to an optional mapping; model update_column() also accepts a title string directly.

Public records and helpers

Card.from_definition() intentionally uses the default schema and returns the fixed dataclass. Use a BoardModel(fields=...) when custom keys must remain in the result.

Errors and lifecycle

BoardModelError subclasses ValueError and is raised for invalid records, schemas, IDs, indices, relationships, updates, protected deletions, and board actions disabled by configuration. Configuration helpers also use TypeError for incorrect value kinds and ValueError for invalid names/ranges. Theme helpers reject unknown token names with ValueError; CustomTkinter may report invalid token values later while constructing a widget.

Editor validation errors are shown in the drawer and keep it open. Public method errors are not swallowed. on_change and on_card_open callback exceptions are logged so the Tk interaction can finish; async success/error callbacks are application code and should handle their own failures.

All widget construction, mutations, and direct UI access should occur on the Tk thread. load_async() is the provided exception: only its fetch callable runs in a daemon worker, and that callable must stay independent of Tk. Call destroy() during normal widget teardown; it invalidates outstanding async delivery and cleans up window-level bindings and local drag state.

Migrating from 1.x

Version 2 is intentionally breaking. Replace mutation-specific callbacks with on_change, and import from ctk_kanban rather than CTkKanBan. The focused 2.0 API initially removed dynamic fields; the current schema API restores that capability without restoring the former persistence, filtering, sorting, and large constructor-flag frameworks. Custom record keys are now preserved.

Migrate stored records by aliasing each card's owning value to column, keep IDs stable and type-consistent, and add field definitions for values that need UI, validation, search, or compact display. Leave integration-only keys undefined in the schema if they only need to round-trip.

Development

python -m pip install -e ".[dev]"
python -m pytest -q
python -m ruff check .
python -m mypy ctk_kanban
python -m build

Release maintainers should also read docs/publishing.md. The changelog records user-visible behavior in CHANGELOG.md.