Table

Usage

The simplest way to create a Table is to pass a list of tuples containing the items to display, and a list of column headings. The values in the tuples will then be mapped sequentially to the columns.

In this example, we will display a table of 2 columns, with 3 initial rows of data:

import toga

table = toga.Table(
    columns=["Name", "Age"],
    data=[
        ("Arthur Dent", 42),
        ("Ford Prefect", 37),
        ("Tricia McMillan", 38),
    ]
)

# Get the details of the first item in the data:
print(f"{table.data[0].name} is age {table.data[0].age}")

# Append new data to the table
table.data.append(("Zaphod Beeblebrox", 47))

You can also specify data for a Table using a list of dictionaries. This allows you to store data in the data source that won't be displayed in the table. It also allows you to control the display order of columns independent of the storage of that data.

import toga

table = toga.Table(
    columns=["Name", "Age"],
    data=[
        {"name": "Arthur Dent", "age": 42, "planet": "Earth"},
        {"name": "Ford Prefect", "age": 37, "planet": "Betelgeuse Five"},
        {"name": "Tricia McMillan", "age": 38, "planet": "Earth"},
    ]
)

# Get the details of the first item in the data:
row = table.data[0]
print(f"{row.name}, who is age {row.age}, is from {row.planet}")

The strings for the headings are translated into AccessorColumn objects which tell the Table how to get the values to display in the column by looking up attributes on the rows.

The accessors are created automatically from the headings, by:

1. Converting the heading to lower case
2. Removing any character that can't be used in a Python identifier
3. Replacing all whitespace with _
4. Prepending _ if the first character is a digit

If you want to use attributes which don't match the headings, you can override them by providing your own AccessorColumn objects. In this example, the table will use "Name" as the visible header, but internally, the attribute "character" will be used:

import toga

table = toga.Table(
    columns=[
        AccessorColumn("Name", "character"),
        "Age",
    ],
    data=[
        {"character": "Arthur Dent", "age": 42, "planet": "Earth"},
        {"character": "Ford Prefect", "age": 37, "planet": "Betelgeuse Five"},
        {"name": "Tricia McMillan", "age": 38, "planet": "Earth"},
    ]
)

# Get the details of the first item in the data:
row = table.data[0]
print(f"{row.character}, who is age {row.age}, is from {row.planet}")

The value provided by an accessor is interpreted as follows:

• If the value is a Widget, that widget will be displayed in the cell. Note that this is currently a beta API: see the Notes section.
• If the value is a [tuple][], it must have two elements: an icon, and a second element which will be interpreted as one of the options below. A tuple of any other length will raise an error.
• If the value is None, then missing_value will be displayed.
• Any other value will be converted into a string. If an icon has not already been provided in a tuple, it can also be provided using the value's icon attribute.

Icon values must either be an Icon, which will be displayed on the left of the cell, or None to display no icon.

So for example:

import toga

green_icon = toga.Icon("icons/green")

table = toga.Table(
    columns=["Name", "Age"],
    data=[
        ((green_icon, "Arthur Dent"), 42),
        ((None, "Ford Prefect"), 37),
        ("Tricia McMillan", 38),
    ]
)

will display the green icon in the first column of the first row and no other icons.

The AccessorColumn class is the only column class provided in core Toga, but you can define your own custom columns that implement the ColumnT protocol and there is a Column abstract base class that serves as a useful starting point. These columns can do things like giving you better control over getting icons and text, formatting in a particular way, combining multiple attributes to produce the value to display, or even accessing data via indexes rather than attribute lookup.

Sometimes when supplying rows using lists or other sequences, the order of the columns may not match the order of the data in the rows. In this case, the easiest approach is to create a [ListSource][toga.sources.ListSource] that maps the rows to the column accessors:

import toga

table = toga.Table(
    columns=["Age", "Name"],
    data=toga.sources.ListSource(
        accessors=["name", "planet", "age"],
        [
            ("Arthur Dent", "Earth", 42),
            ("Ford Prefect", "Betelgeuse Five", 37),
            ("Tricia McMillan", "Earth", 38),
        ],
    )
)

For more complex data you can define your own custom data sources.

Notes

• Widgets in cells is a beta API which may change in future, and is currently only supported on macOS.
• macOS does not support changing the font used to render table content.
• Icons in tables are not supported on Android, and the implementation is not scalable beyond about 1,000 cells.

Reference

Bases: Widget, Generic[Value]

Source code in core/src/toga/widgets/table.py

class Table(Widget, Generic[Value]):
    def __init__(
        self,
        columns: Iterable[str | ColumnT[Value]] | None = None,
        id: str | None = None,
        style: StyleT | None = None,
        data: ListSourceT | Iterable | None = None,
        accessors: Iterable[str] | None = None,
        multiple_select: bool = False,
        on_select: toga.widgets.table.OnSelectHandler | None = None,
        on_activate: toga.widgets.table.OnActivateHandler | None = None,
        missing_value: str = "",
        *,
        show_headings: bool | None = None,
        headings: Iterable[str] | None = None,
        **kwargs,
    ):
        """Create a new Table widget.

        :param columns: The column objects or heading strings for the table. Column
            objects must implement the [`ColumnT`][toga.sources.ColumnT] protocol.
            Heading strings will be converted to
            [`AccessorColumn`][toga.sources.AccessorColumn] instances automatically.
            Heading strings can only contain one line; any text after a newline will be
            ignored.

            **DEPRECATED:** A value of [`None`][] will produce a table without headings.
            Rather than specifying a value of [`None`][] for `columns`, you should use
            `show_headings=False`. However, if you *do* specify [`None`][] for columns,
            you *must* provide a list of accessors.
        :param id: The ID for the widget.
        :param style: A style object. If no style is provided, a default style will be
            applied to the widget.
        :param data: Initial [`data`][toga.Table.data] to be displayed in the table.
            This can be an object which implements the `ListSourceT` protocol, an
            Iterable object, or [`None`][]. An Iterable object will be automatically
            converted to a [`ListSource`][toga.sources.ListSource].
        :param accessors: **DEPRECATED** To specify a non-default accessor name for a
            column, specify columns using
            ['AccessorColumn'][toga.sources.AccessorColumn] instances. To specify the
            ordering of items in table data, specify `data` using a
            [`ListSource`][toga.sources.ListSource] with an `accessors` argument.

            When table data is provided as an iterable, the
            [`ListSource`][toga.sources.ListSource] created by the Table will try to
            derive its accessors from the column definitions. However, when the table
            data has entries that will not be displayed in the table, or when the
            autogenerated attribute for a column doesn't produce the required value, it
            may be necessary to override the list of accessors used to populate the
            table.

            The `accessors` argument must be either:

            * A list, at least as long as `columns`, specifying the accessors for each
              column plus any additional accessors.  When the column is given by a
              heading string then the heading and accessor will be used to create an
              [`AccessorColumn`][toga.sources.AccessorColumn]; or

            * A dictionary mapping heading strings to accessors. When the column is
              given by a heading string then the heading and accessor will be used to
              create an [`AccessorColumn`][toga.sources.AccessorColumn].  Any missing
              headings will fall back to the default generated accessor.

            The default value of [`None`][] results in accessors being derived from the
            columns.

            If no columns or heading strings were provided, an
            ['AccessorColumn'][toga.sources.AccessorColumn] instance will be created for
            each accessor and a table with no headings will be created.

            The accessors are also passed to any [`ListSource`][toga.sources.ListSource]
            created by the Table to tell the source how to map lists and tuples to
            accessor values. This ordering does not change even when columns are added
            or removed.
        :param multiple_select: Does the table allow multiple selection?
        :param on_select: Initial [`on_select`][toga.Table.on_select] handler.
        :param on_activate: Initial [`on_activate`][toga.Table.on_activate] handler.
        :param missing_value: The string that will be used to populate a cell when the
            value provided by its accessor is [`None`][], or the accessor isn't defined.
        :param show_headings: Whether or not to show headings at the top of the table.
            For backwards compatibility, this is set to False if no columns or headings
            are provided.
        :param headings: **DEPRECATED** A list of heading strings for columns.
        :param kwargs: Initial style properties.
        """
        self._data: ListSourceT | ListSource

        self._missing_value = missing_value if missing_value else ""
        self._multiple_select = multiple_select

        # Prime some properties that need to exist before the table is created.
        self.on_select = None
        self.on_activate = None

        ######################################################################
        # 2026-02: Backwards compatibility for <= 0.5.3
        ######################################################################
        if headings is not None:
            if columns is None:
                warnings.warn(
                    "The 'headings' keyword argument is deprecated; "
                    "use 'columns' instead.",
                    DeprecationWarning,
                    stacklevel=2,
                )
                columns = headings
            else:
                raise TypeError("Can't specify columns and headings at the same time.")

        if accessors is not None:
            warnings.warn(
                "The `accessors` argument is deprecated. To specify a non-default "
                "accessor for a column, use an `AccessorColumn`. To specify the "
                "ordering of accessors use a `ListSource` with an `accessors` "
                "argument for the data.",
                DeprecationWarning,
                stacklevel=2,
            )

        if columns is None:
            if accessors is None:
                raise ValueError(
                    "Cannot create a table without either columns or accessors."
                )
            columns = AccessorColumn.columns_from_headings_and_accessors(
                None, accessors
            )
            if show_headings is None:
                # Don't show headings if only given accessors.
                show_headings = False
        elif isinstance(accessors, Mapping):
            columns = [
                AccessorColumn(column, accessors.get(column, None))
                if isinstance(column, str)
                else column
                for column in columns
            ]
        elif accessors is not None:
            columns = [
                AccessorColumn(column, accessor) if isinstance(column, str) else column
                for column, accessor in zip(columns, accessors, strict=False)
            ]
        ######################################################################
        # End backwards compatibility
        ######################################################################
        else:
            columns = [
                AccessorColumn(column) if isinstance(column, str) else column
                for column in columns
            ]

        ######################################################################
        # 2026-02: Backwards compatibility for <= 0.5.3
        #
        # When removing backwards compatibility for accessors, show_headings can
        # default to True, and this logic can be removed.
        ######################################################################
        self._show_headings = show_headings if show_headings is not None else True
        ######################################################################
        # End backwards compatibility
        ######################################################################

        self._columns: list[ColumnT] = columns

        # Prime some properties that need to exist before the tree is created.
        self.on_select = None
        self.on_activate = None

        super().__init__(id, style, **kwargs)

        if not isinstance(data, Source):
            if accessors is None or isinstance(accessors, Mapping):
                # Use the column's accessors
                accessor_order = [
                    column.accessor
                    for column in columns
                    if getattr(column, "accessor", None) is not None
                ]
            else:
                # use the accessors parameter
                accessor_order = list(accessors)

            if data is None:
                data = ListSource(accessors=accessor_order, data=[])
            else:
                data = ListSource(accessors=accessor_order, data=data)

        self.data = data

        self.on_select = on_select
        self.on_activate = on_activate

    def _create(self) -> Any:
        return self.factory.Table(interface=self)

    @property
    def enabled(self) -> Literal[True]:
        """Is the widget currently enabled? i.e., can the user interact with the widget?
        Table widgets cannot be disabled; this property will always return True; any
        attempt to modify it will be ignored.
        """
        return True

    @enabled.setter
    def enabled(self, value: object) -> None:
        pass

    @property
    def data(self) -> ListSourceT | ListSource:
        """The data to display in the table.

        When setting this property:

        * A [`Source`][toga.sources.Source] will be used as-is. It must either be a
          [`ListSource`][toga.sources.ListSource], or
          a custom class that provides the same methods.

        * A value of None is turned into an empty ListSource.

        * Otherwise, the value must be an iterable, which is copied into a new
          ListSource. Items are converted as shown [here][listsource-item].

        In the last two cases, when creating a new or empty ListSource, the
        accessors of the old source are copied to the new one or, if that is
        impossible, the accessors of the columns are used.
        """
        return self._data

    @data.setter
    def data(self, data: ListSourceT | Iterable | None) -> None:
        old_data = getattr(self, "_data", None)
        if old_data is not None:
            self._data.remove_listener(self._impl)

        if data is None:
            data = []

        if isinstance(data, Source):
            self._data = data
        else:
            # try to copy the accessors from the previous data source
            accessors = getattr(old_data, "accessors", None)
            if accessors is None:
                # failing that, use the accessors from the columns, if any
                accessors = [
                    column.accessor
                    for column in self.columns
                    if getattr(column, "accessor", None) is not None
                ]
            self._data = ListSource(accessors=accessors, data=data)

        self._data.add_listener(self._impl)
        self._impl.change_source(source=self._data)

    @property
    def multiple_select(self) -> bool:
        """Does the table allow multiple rows to be selected?"""
        return self._multiple_select

    @property
    def selection(self) -> list[Row] | Row | None:
        """The current selection of the table.

        If multiple selection is enabled, returns a list of Row objects from the data
        source matching the current selection. An empty list is returned if no rows are
        selected.

        If multiple selection is *not* enabled, returns the selected Row object, or
        [`None`][] if no row is currently selected.
        """
        selection = self._impl.get_selection()
        if isinstance(selection, list):
            return [self.data[index] for index in selection]
        elif selection is None:
            return None
        else:
            return self.data[selection]

    def scroll_to_top(self) -> None:
        """Scroll the view so that the top of the list (first row) is visible."""
        self.scroll_to_row(0)

    def scroll_to_row(self, row: int) -> None:
        """Scroll the view so that the specified row index is visible.

        :param row: The index of the row to make visible. Negative values refer to the
            nth last row (-1 is the last row, -2 second last, and so on).
        """
        if len(self.data) > 1:
            if row >= 0:
                self._impl.scroll_to_row(min(row, len(self.data)))
            else:
                self._impl.scroll_to_row(max(len(self.data) + row, 0))

    def scroll_to_bottom(self) -> None:
        """Scroll the view so that the bottom of the list (last row) is visible."""
        self.scroll_to_row(-1)

    @property
    def on_select(self) -> OnSelectHandler:
        """The callback function that is invoked when a row of the table is selected."""
        return self._on_select

    @on_select.setter
    def on_select(self, handler: toga.widgets.table.OnSelectHandler) -> None:
        self._on_select = wrapped_handler(self, handler)

    @property
    def on_activate(self) -> OnActivateHandler:
        """The callback function that is invoked when a row of the table is activated,
        usually with a double click or similar action."""
        return self._on_activate

    @on_activate.setter
    def on_activate(self, handler: toga.widgets.table.OnActivateHandler) -> None:
        self._on_activate = wrapped_handler(self, handler)

    def append_column(
        self,
        column: ColumnT[Value] | str | None = None,
        accessor: str | None = None,
        *,
        heading: str | None = None,
    ) -> None:
        """Append a column to the end of the table.

        :param column: The new column, or a heading string for the new column.
        :param accessor: **DEPRECATED** To specify a non-default accessor for a column,
            use an [`AccessorColumn`][toga.sources.AccessorColumn]. To specify the
            ordering of accessors use a [`ListSource`][toga.sources.ListSource] with an
            `accessors` argument for the data.

            An accessor to use if a heading string is supplied rather than a column
            object. If not specified, an accessor will be derived from the heading. An
            accessor *must* be specified if the column is None.
        """
        ######################################################################
        # 2026-02: Backwards compatibility for <= 0.5.3
        ######################################################################
        if heading is not None:
            if column is None:
                warnings.warn(
                    "The 'heading' keyword argument is deprecated; "
                    "use 'column' instead.",
                    DeprecationWarning,
                    stacklevel=2,
                )
                column = heading
            else:
                raise TypeError("Can't specify both 'column' and 'heading' arguments.")

        # Deprecation of accessor is flagged by insert_column()

        ######################################################################
        # End backwards compatibility
        ######################################################################
        self.insert_column(len(self._columns), column, accessor=accessor)

    def insert_column(
        self,
        index: int | ColumnT[Value] | str,
        column: ColumnT[Value] | str | None = None,
        accessor: str | None = None,
        *,
        heading: str | None = None,
    ) -> None:
        """Insert an additional column into the table.

        :param index: The index at which to insert the column, or the column (or its
            accessor **DEPRECATED**) before which the new column should be inserted.
        :param column: The new column, or a heading string for the new column.
        :param accessor: **DEPRECATED** To specify a non-default accessor for a column,
            use an [`AccessorColumn`][toga.sources.AccessorColumn]. To specify the
            ordering of accessors use a [`ListSource`][toga.sources.ListSource] with an
            `accessors` argument for the data.

            An accessor to use if a heading string is supplied rather than a column
            object. If not specified, an accessor will be derived from the heading. An
            accessor *must* be specified if the column is None.
        """
        ######################################################################
        # 2026-02: Backwards compatibility for <= 0.5.3
        ######################################################################
        if heading is not None:
            if column is None:
                warnings.warn(
                    "The 'heading' keyword argument is deprecated; "
                    "use 'column' instead.",
                    DeprecationWarning,
                    stacklevel=2,
                )
                column = heading
            else:
                raise TypeError("Can't specify both 'column' and 'heading' arguments.")

        if accessor is not None:
            warnings.warn(
                "The `accessor` argument is deprecated. To specify a non-default "
                "accessor for a column, use an `AccessorColumn`. To specify the "
                "ordering of accessors use a `ListSource` with an `accessors` "
                "argument for the data.",
                DeprecationWarning,
                stacklevel=2,
            )
        ######################################################################
        # End backwards compatibility
        ######################################################################
        if column is None and accessor is None:
            raise ValueError("Must specify either a column or an accessor.")
        elif isinstance(column, str) and not self._show_headings and accessor is None:
            raise ValueError("Must specify an accessor on a table without headings.")
        elif isinstance(column, str) or column is None:
            column = AccessorColumn(column, accessor)
        elif accessor is not None:
            warnings.warn(
                "The 'accessor' argument is ignored when a column object is supplied.",
                stacklevel=2,
            )

        ######################################################################
        # 2026-02: Backwards compatibility for <= 0.5.3
        ######################################################################
        if isinstance(index, str):
            index = self.accessors.index(index)
        ######################################################################
        # End backwards compatibility
        ######################################################################
        elif not isinstance(index, int):
            index = self._columns.index(index)
        else:
            # Re-interpret negative indices, and clip indices outside valid range.
            if index < 0:
                index = max(len(self._columns) + index, 0)
            else:
                index = min(len(self._columns), index)

        self._columns.insert(index, column)
        try:
            self._impl.insert_column(index, column)
        except TypeError:
            ######################################################################
            # 2026-02: Backwards compatibility for <= 0.5.3
            ######################################################################
            warnings.warn(
                "Table implementations of insert_column should expect a column object "
                "not heading and accessor.",
                DeprecationWarning,
                stacklevel=2,
            )
            self._impl.insert_column(
                index, column.heading, getattr(column, "accessor", None)
            )
            ######################################################################
            # End backwards compatibility
            ######################################################################

    def remove_column(self, column: int | ColumnT[Value] | str) -> None:
        """Remove a table column.

        :param column: The index of the column to remove, or the column (or its
            accessor [Deprecated]) to remove.
        """
        ######################################################################
        # 2026-02: Backwards compatibility for <= 0.5.3
        ######################################################################
        if isinstance(column, str):
            index = self.accessors.index(column)
        ######################################################################
        # End backwards compatibility
        ######################################################################
        elif not isinstance(column, int):
            index = self._columns.index(column)
        else:
            if column < 0:
                index = len(self._columns) + column
            else:
                index = column

        # Remove column
        del self._columns[index]
        self._impl.remove_column(index)

    @property
    def show_headings(self) -> bool:
        """Whether or not the table shows a header at the top (read-only)"""
        return self._show_headings

    @property
    def columns(self) -> list[ColumnT[Value]]:
        """The columns for the table (read-only)"""
        return self._columns.copy()

    @property
    def headings(self) -> list[str] | None:
        """The column headings for the table, or None if there are no headings
        (read-only)
        """
        if not self._show_headings:
            return None
        else:
            return [column.heading for column in self._columns]

    ######################################################################
    # 2026-02: Backwards compatibility for <= 0.5.3
    ######################################################################
    @property
    def accessors(self) -> list[str | None]:
        """The list of column accessors (read-only) [Deprecated]"""
        warnings.warn(
            "Using accessors is deprecated; use columns instead.",
            DeprecationWarning,
            stacklevel=2,
        )
        return [getattr(column, "accessor", None) for column in self._columns]

    ######################################################################
    # End backwards compatibility
    ######################################################################

    @property
    def missing_value(self) -> str:
        """The value that will be used when a data row doesn't provide a value for an
        attribute.
        """
        return self._missing_value

accessors property

The list of column accessors (read-only) [Deprecated]

columns property

The columns for the table (read-only)

data property writable

The data to display in the table.

When setting this property:

• A Source will be used as-is. It must either be a ListSource, or a custom class that provides the same methods.

• A value of None is turned into an empty ListSource.

• Otherwise, the value must be an iterable, which is copied into a new ListSource. Items are converted as shown here.

In the last two cases, when creating a new or empty ListSource, the accessors of the old source are copied to the new one or, if that is impossible, the accessors of the columns are used.

enabled property writable

Is the widget currently enabled? i.e., can the user interact with the widget? Table widgets cannot be disabled; this property will always return True; any attempt to modify it will be ignored.

headings property

The column headings for the table, or None if there are no headings (read-only)

missing_value property

The value that will be used when a data row doesn't provide a value for an attribute.

multiple_select property

Does the table allow multiple rows to be selected?

on_activate property writable

The callback function that is invoked when a row of the table is activated, usually with a double click or similar action.

on_select property writable

The callback function that is invoked when a row of the table is selected.

selection property

The current selection of the table.

If multiple selection is enabled, returns a list of Row objects from the data source matching the current selection. An empty list is returned if no rows are selected.

If multiple selection is not enabled, returns the selected Row object, or [None][] if no row is currently selected.

show_headings property

Whether or not the table shows a header at the top (read-only)

__init__(columns=None, id=None, style=None, data=None, accessors=None, multiple_select=False, on_select=None, on_activate=None, missing_value='', *, show_headings=None, headings=None, **kwargs)

Create a new Table widget.

:param columns: The column objects or heading strings for the table. Column objects must implement the ColumnT protocol. Heading strings will be converted to AccessorColumn instances automatically. Heading strings can only contain one line; any text after a newline will be ignored.

**DEPRECATED:** A value of [`None`][] will produce a table without headings.
Rather than specifying a value of [`None`][] for `columns`, you should use
`show_headings=False`. However, if you *do* specify [`None`][] for columns,
you *must* provide a list of accessors.

:param id: The ID for the widget. :param style: A style object. If no style is provided, a default style will be applied to the widget. :param data: Initial data to be displayed in the table. This can be an object which implements the ListSourceT protocol, an Iterable object, or [None][]. An Iterable object will be automatically converted to a ListSource. :param accessors: DEPRECATED To specify a non-default accessor name for a column, specify columns using 'AccessorColumn' instances. To specify the ordering of items in table data, specify data using a ListSource with an accessors argument.

When table data is provided as an iterable, the
[`ListSource`][toga.sources.ListSource] created by the Table will try to
derive its accessors from the column definitions. However, when the table
data has entries that will not be displayed in the table, or when the
autogenerated attribute for a column doesn't produce the required value, it
may be necessary to override the list of accessors used to populate the
table.

The `accessors` argument must be either:

* A list, at least as long as `columns`, specifying the accessors for each
  column plus any additional accessors.  When the column is given by a
  heading string then the heading and accessor will be used to create an
  [`AccessorColumn`][toga.sources.AccessorColumn]; or

* A dictionary mapping heading strings to accessors. When the column is
  given by a heading string then the heading and accessor will be used to
  create an [`AccessorColumn`][toga.sources.AccessorColumn].  Any missing
  headings will fall back to the default generated accessor.

The default value of [`None`][] results in accessors being derived from the
columns.

If no columns or heading strings were provided, an
['AccessorColumn'][toga.sources.AccessorColumn] instance will be created for
each accessor and a table with no headings will be created.

The accessors are also passed to any [`ListSource`][toga.sources.ListSource]
created by the Table to tell the source how to map lists and tuples to
accessor values. This ordering does not change even when columns are added
or removed.

:param multiple_select: Does the table allow multiple selection? :param on_select: Initial on_select handler. :param on_activate: Initial on_activate handler. :param missing_value: The string that will be used to populate a cell when the value provided by its accessor is [None][], or the accessor isn't defined. :param show_headings: Whether or not to show headings at the top of the table. For backwards compatibility, this is set to False if no columns or headings are provided. :param headings: DEPRECATED A list of heading strings for columns. :param kwargs: Initial style properties.

Source code in core/src/toga/widgets/table.py

def __init__(
    self,
    columns: Iterable[str | ColumnT[Value]] | None = None,
    id: str | None = None,
    style: StyleT | None = None,
    data: ListSourceT | Iterable | None = None,
    accessors: Iterable[str] | None = None,
    multiple_select: bool = False,
    on_select: toga.widgets.table.OnSelectHandler | None = None,
    on_activate: toga.widgets.table.OnActivateHandler | None = None,
    missing_value: str = "",
    *,
    show_headings: bool | None = None,
    headings: Iterable[str] | None = None,
    **kwargs,
):
    """Create a new Table widget.

    :param columns: The column objects or heading strings for the table. Column
        objects must implement the [`ColumnT`][toga.sources.ColumnT] protocol.
        Heading strings will be converted to
        [`AccessorColumn`][toga.sources.AccessorColumn] instances automatically.
        Heading strings can only contain one line; any text after a newline will be
        ignored.

        **DEPRECATED:** A value of [`None`][] will produce a table without headings.
        Rather than specifying a value of [`None`][] for `columns`, you should use
        `show_headings=False`. However, if you *do* specify [`None`][] for columns,
        you *must* provide a list of accessors.
    :param id: The ID for the widget.
    :param style: A style object. If no style is provided, a default style will be
        applied to the widget.
    :param data: Initial [`data`][toga.Table.data] to be displayed in the table.
        This can be an object which implements the `ListSourceT` protocol, an
        Iterable object, or [`None`][]. An Iterable object will be automatically
        converted to a [`ListSource`][toga.sources.ListSource].
    :param accessors: **DEPRECATED** To specify a non-default accessor name for a
        column, specify columns using
        ['AccessorColumn'][toga.sources.AccessorColumn] instances. To specify the
        ordering of items in table data, specify `data` using a
        [`ListSource`][toga.sources.ListSource] with an `accessors` argument.

        When table data is provided as an iterable, the
        [`ListSource`][toga.sources.ListSource] created by the Table will try to
        derive its accessors from the column definitions. However, when the table
        data has entries that will not be displayed in the table, or when the
        autogenerated attribute for a column doesn't produce the required value, it
        may be necessary to override the list of accessors used to populate the
        table.

        The `accessors` argument must be either:

        * A list, at least as long as `columns`, specifying the accessors for each
          column plus any additional accessors.  When the column is given by a
          heading string then the heading and accessor will be used to create an
          [`AccessorColumn`][toga.sources.AccessorColumn]; or

        * A dictionary mapping heading strings to accessors. When the column is
          given by a heading string then the heading and accessor will be used to
          create an [`AccessorColumn`][toga.sources.AccessorColumn].  Any missing
          headings will fall back to the default generated accessor.

        The default value of [`None`][] results in accessors being derived from the
        columns.

        If no columns or heading strings were provided, an
        ['AccessorColumn'][toga.sources.AccessorColumn] instance will be created for
        each accessor and a table with no headings will be created.

        The accessors are also passed to any [`ListSource`][toga.sources.ListSource]
        created by the Table to tell the source how to map lists and tuples to
        accessor values. This ordering does not change even when columns are added
        or removed.
    :param multiple_select: Does the table allow multiple selection?
    :param on_select: Initial [`on_select`][toga.Table.on_select] handler.
    :param on_activate: Initial [`on_activate`][toga.Table.on_activate] handler.
    :param missing_value: The string that will be used to populate a cell when the
        value provided by its accessor is [`None`][], or the accessor isn't defined.
    :param show_headings: Whether or not to show headings at the top of the table.
        For backwards compatibility, this is set to False if no columns or headings
        are provided.
    :param headings: **DEPRECATED** A list of heading strings for columns.
    :param kwargs: Initial style properties.
    """
    self._data: ListSourceT | ListSource

    self._missing_value = missing_value if missing_value else ""
    self._multiple_select = multiple_select

    # Prime some properties that need to exist before the table is created.
    self.on_select = None
    self.on_activate = None

    ######################################################################
    # 2026-02: Backwards compatibility for <= 0.5.3
    ######################################################################
    if headings is not None:
        if columns is None:
            warnings.warn(
                "The 'headings' keyword argument is deprecated; "
                "use 'columns' instead.",
                DeprecationWarning,
                stacklevel=2,
            )
            columns = headings
        else:
            raise TypeError("Can't specify columns and headings at the same time.")

    if accessors is not None:
        warnings.warn(
            "The `accessors` argument is deprecated. To specify a non-default "
            "accessor for a column, use an `AccessorColumn`. To specify the "
            "ordering of accessors use a `ListSource` with an `accessors` "
            "argument for the data.",
            DeprecationWarning,
            stacklevel=2,
        )

    if columns is None:
        if accessors is None:
            raise ValueError(
                "Cannot create a table without either columns or accessors."
            )
        columns = AccessorColumn.columns_from_headings_and_accessors(
            None, accessors
        )
        if show_headings is None:
            # Don't show headings if only given accessors.
            show_headings = False
    elif isinstance(accessors, Mapping):
        columns = [
            AccessorColumn(column, accessors.get(column, None))
            if isinstance(column, str)
            else column
            for column in columns
        ]
    elif accessors is not None:
        columns = [
            AccessorColumn(column, accessor) if isinstance(column, str) else column
            for column, accessor in zip(columns, accessors, strict=False)
        ]
    ######################################################################
    # End backwards compatibility
    ######################################################################
    else:
        columns = [
            AccessorColumn(column) if isinstance(column, str) else column
            for column in columns
        ]

    ######################################################################
    # 2026-02: Backwards compatibility for <= 0.5.3
    #
    # When removing backwards compatibility for accessors, show_headings can
    # default to True, and this logic can be removed.
    ######################################################################
    self._show_headings = show_headings if show_headings is not None else True
    ######################################################################
    # End backwards compatibility
    ######################################################################

    self._columns: list[ColumnT] = columns

    # Prime some properties that need to exist before the tree is created.
    self.on_select = None
    self.on_activate = None

    super().__init__(id, style, **kwargs)

    if not isinstance(data, Source):
        if accessors is None or isinstance(accessors, Mapping):
            # Use the column's accessors
            accessor_order = [
                column.accessor
                for column in columns
                if getattr(column, "accessor", None) is not None
            ]
        else:
            # use the accessors parameter
            accessor_order = list(accessors)

        if data is None:
            data = ListSource(accessors=accessor_order, data=[])
        else:
            data = ListSource(accessors=accessor_order, data=data)

    self.data = data

    self.on_select = on_select
    self.on_activate = on_activate

append_column(column=None, accessor=None, *, heading=None)

Append a column to the end of the table.

:param column: The new column, or a heading string for the new column. :param accessor: DEPRECATED To specify a non-default accessor for a column, use an AccessorColumn. To specify the ordering of accessors use a ListSource with an accessors argument for the data.

An accessor to use if a heading string is supplied rather than a column
object. If not specified, an accessor will be derived from the heading. An
accessor *must* be specified if the column is None.

Source code in core/src/toga/widgets/table.py

def append_column(
    self,
    column: ColumnT[Value] | str | None = None,
    accessor: str | None = None,
    *,
    heading: str | None = None,
) -> None:
    """Append a column to the end of the table.

    :param column: The new column, or a heading string for the new column.
    :param accessor: **DEPRECATED** To specify a non-default accessor for a column,
        use an [`AccessorColumn`][toga.sources.AccessorColumn]. To specify the
        ordering of accessors use a [`ListSource`][toga.sources.ListSource] with an
        `accessors` argument for the data.

        An accessor to use if a heading string is supplied rather than a column
        object. If not specified, an accessor will be derived from the heading. An
        accessor *must* be specified if the column is None.
    """
    ######################################################################
    # 2026-02: Backwards compatibility for <= 0.5.3
    ######################################################################
    if heading is not None:
        if column is None:
            warnings.warn(
                "The 'heading' keyword argument is deprecated; "
                "use 'column' instead.",
                DeprecationWarning,
                stacklevel=2,
            )
            column = heading
        else:
            raise TypeError("Can't specify both 'column' and 'heading' arguments.")

    # Deprecation of accessor is flagged by insert_column()

    ######################################################################
    # End backwards compatibility
    ######################################################################
    self.insert_column(len(self._columns), column, accessor=accessor)

insert_column(index, column=None, accessor=None, *, heading=None)

Insert an additional column into the table.

:param index: The index at which to insert the column, or the column (or its accessor DEPRECATED) before which the new column should be inserted. :param column: The new column, or a heading string for the new column. :param accessor: DEPRECATED To specify a non-default accessor for a column, use an AccessorColumn. To specify the ordering of accessors use a ListSource with an accessors argument for the data.

An accessor to use if a heading string is supplied rather than a column
object. If not specified, an accessor will be derived from the heading. An
accessor *must* be specified if the column is None.

Source code in core/src/toga/widgets/table.py

def insert_column(
    self,
    index: int | ColumnT[Value] | str,
    column: ColumnT[Value] | str | None = None,
    accessor: str | None = None,
    *,
    heading: str | None = None,
) -> None:
    """Insert an additional column into the table.

    :param index: The index at which to insert the column, or the column (or its
        accessor **DEPRECATED**) before which the new column should be inserted.
    :param column: The new column, or a heading string for the new column.
    :param accessor: **DEPRECATED** To specify a non-default accessor for a column,
        use an [`AccessorColumn`][toga.sources.AccessorColumn]. To specify the
        ordering of accessors use a [`ListSource`][toga.sources.ListSource] with an
        `accessors` argument for the data.

        An accessor to use if a heading string is supplied rather than a column
        object. If not specified, an accessor will be derived from the heading. An
        accessor *must* be specified if the column is None.
    """
    ######################################################################
    # 2026-02: Backwards compatibility for <= 0.5.3
    ######################################################################
    if heading is not None:
        if column is None:
            warnings.warn(
                "The 'heading' keyword argument is deprecated; "
                "use 'column' instead.",
                DeprecationWarning,
                stacklevel=2,
            )
            column = heading
        else:
            raise TypeError("Can't specify both 'column' and 'heading' arguments.")

    if accessor is not None:
        warnings.warn(
            "The `accessor` argument is deprecated. To specify a non-default "
            "accessor for a column, use an `AccessorColumn`. To specify the "
            "ordering of accessors use a `ListSource` with an `accessors` "
            "argument for the data.",
            DeprecationWarning,
            stacklevel=2,
        )
    ######################################################################
    # End backwards compatibility
    ######################################################################
    if column is None and accessor is None:
        raise ValueError("Must specify either a column or an accessor.")
    elif isinstance(column, str) and not self._show_headings and accessor is None:
        raise ValueError("Must specify an accessor on a table without headings.")
    elif isinstance(column, str) or column is None:
        column = AccessorColumn(column, accessor)
    elif accessor is not None:
        warnings.warn(
            "The 'accessor' argument is ignored when a column object is supplied.",
            stacklevel=2,
        )

    ######################################################################
    # 2026-02: Backwards compatibility for <= 0.5.3
    ######################################################################
    if isinstance(index, str):
        index = self.accessors.index(index)
    ######################################################################
    # End backwards compatibility
    ######################################################################
    elif not isinstance(index, int):
        index = self._columns.index(index)
    else:
        # Re-interpret negative indices, and clip indices outside valid range.
        if index < 0:
            index = max(len(self._columns) + index, 0)
        else:
            index = min(len(self._columns), index)

    self._columns.insert(index, column)
    try:
        self._impl.insert_column(index, column)
    except TypeError:
        ######################################################################
        # 2026-02: Backwards compatibility for <= 0.5.3
        ######################################################################
        warnings.warn(
            "Table implementations of insert_column should expect a column object "
            "not heading and accessor.",
            DeprecationWarning,
            stacklevel=2,
        )
        self._impl.insert_column(
            index, column.heading, getattr(column, "accessor", None)
        )

remove_column(column)

Remove a table column.

:param column: The index of the column to remove, or the column (or its accessor [Deprecated]) to remove.

Source code in core/src/toga/widgets/table.py

def remove_column(self, column: int | ColumnT[Value] | str) -> None:
    """Remove a table column.

    :param column: The index of the column to remove, or the column (or its
        accessor [Deprecated]) to remove.
    """
    ######################################################################
    # 2026-02: Backwards compatibility for <= 0.5.3
    ######################################################################
    if isinstance(column, str):
        index = self.accessors.index(column)
    ######################################################################
    # End backwards compatibility
    ######################################################################
    elif not isinstance(column, int):
        index = self._columns.index(column)
    else:
        if column < 0:
            index = len(self._columns) + column
        else:
            index = column

    # Remove column
    del self._columns[index]
    self._impl.remove_column(index)

scroll_to_bottom()

Scroll the view so that the bottom of the list (last row) is visible.

Source code in core/src/toga/widgets/table.py

def scroll_to_bottom(self) -> None:
    """Scroll the view so that the bottom of the list (last row) is visible."""
    self.scroll_to_row(-1)

scroll_to_row(row)

Scroll the view so that the specified row index is visible.

:param row: The index of the row to make visible. Negative values refer to the nth last row (-1 is the last row, -2 second last, and so on).

Source code in core/src/toga/widgets/table.py

def scroll_to_row(self, row: int) -> None:
    """Scroll the view so that the specified row index is visible.

    :param row: The index of the row to make visible. Negative values refer to the
        nth last row (-1 is the last row, -2 second last, and so on).
    """
    if len(self.data) > 1:
        if row >= 0:
            self._impl.scroll_to_row(min(row, len(self.data)))
        else:
            self._impl.scroll_to_row(max(len(self.data) + row, 0))

scroll_to_top()

Scroll the view so that the top of the list (first row) is visible.

Source code in core/src/toga/widgets/table.py

def scroll_to_top(self) -> None:
    """Scroll the view so that the top of the list (first row) is visible."""
    self.scroll_to_row(0)

Bases: Protocol

Source code in core/src/toga/widgets/table.py

class OnSelectHandler(Protocol):
    def __call__(self, widget: Table, **kwargs: Any) -> None:
        """A handler to invoke when the table is selected.

        :param widget: The Table that was selected.
        :param kwargs: Ensures compatibility with arguments added in future versions.
        """

__call__(widget, **kwargs)

A handler to invoke when the table is selected.

:param widget: The Table that was selected. :param kwargs: Ensures compatibility with arguments added in future versions.

Source code in core/src/toga/widgets/table.py

def __call__(self, widget: Table, **kwargs: Any) -> None:
    """A handler to invoke when the table is selected.

    :param widget: The Table that was selected.
    :param kwargs: Ensures compatibility with arguments added in future versions.
    """

Bases: Protocol

Source code in core/src/toga/widgets/table.py

class OnActivateHandler(Protocol):
    def __call__(self, widget: Table, row: Any, **kwargs: Any) -> None:
        """A handler to invoke when the table is activated.

        :param widget: The Table that was activated.
        :param row: The Table Row that was activated.
        :param kwargs: Ensures compatibility with arguments added in future versions.
        """

__call__(widget, row, **kwargs)

A handler to invoke when the table is activated.

:param widget: The Table that was activated. :param row: The Table Row that was activated. :param kwargs: Ensures compatibility with arguments added in future versions.

Source code in core/src/toga/widgets/table.py

def __call__(self, widget: Table, row: Any, **kwargs: Any) -> None:
    """A handler to invoke when the table is activated.

    :param widget: The Table that was activated.
    :param row: The Table Row that was activated.
    :param kwargs: Ensures compatibility with arguments added in future versions.
    """