Raxol.UI.Components.Table (Raxol v0.4.0)

View Source

Table component for displaying and interacting with tabular data.

Features

  • Pagination
  • Sorting
  • Filtering
  • Custom column formatting
  • Row selection
  • Custom theming and styling (see below)

Public API

Props

  • :id (required): Unique identifier for the table.
  • :columns (required): List of column definitions. Each column is a map with:
    • :id (atom, required): Key for the column.
    • :label (string, required): Header label.
    • :width (integer or :auto, optional): Column width.
    • :align (:left | :center | :right, optional): Text alignment.

    • :format (function, optional): Custom formatting function for cell values.
    • :style (map, optional): Style overrides for all cells in this column.
    • :header_style (map, optional): Style overrides for this column's header cell.
  • :data (required): List of row maps (each map must have keys matching column ids).
  • :options (map, optional):
    • :paginate (boolean): Enable pagination.
    • :searchable (boolean): Enable filtering.
    • :sortable (boolean): Enable sorting.
    • :page_size (integer): Rows per page.
  • :style (map, optional): Style overrides for the table box and header (see below).
    • :header (map, optional): Style overrides for all header cells.
  • :theme (map, optional): Theme map for the table. Keys can include:
    • :box (map): Style for the outer box.
    • :header (map): Style for all header cells.
    • :row (map): Style for all rows.
    • :selected_row (map): Style for the selected row.

Theming and Style Precedence

  • Per-column :style and :header_style override theme and table-level styles for their respective cells.
  • :style prop overrides theme for the box and header.
  • :theme provides defaults for box, header, row, and selected row.
  • Hardcoded defaults (e.g., header bold, selected row blue/white) are used if not overridden.

Example: Custom Theming and Styling

columns = [
  %{id: :id, label: "ID", style: %{color: :magenta}, header_style: %{bg: :cyan}},
  %{id: :name, label: "Name"},
  %{id: :age, label: "Age"}
]
data = [%{id: 1, name: "Alice", age: 30}, ...]
theme = %{
  box: %{border_color: :green},
  header: %{underline: true},
  row: %{bg: :yellow},
  selected_row: %{bg: :red, fg: :black}
}
style = %{header: %{italic: true}}

Table.init(%{
  id: :my_table,
  columns: columns,
  data: data,
  theme: theme,
  style: style,
  options: %{paginate: true, page_size: 5}
})

Summary

Functions

Handles events for the table component.

Initializes the table component with the given props.

Callback implementation for Surface.Component.render/1.

Renders the table component.

Updates the table state based on the given message.

Types

column()

@type column() :: %{
  id: atom(),
  label: String.t(),
  width: non_neg_integer() | :auto,
  align: :left | :center | :right,
  format: (term() -> String.t()) | nil
}

options()

@type options() :: %{
  paginate: boolean(),
  searchable: boolean(),
  sortable: boolean(),
  page_size: non_neg_integer()
}

Functions

handle_event(arg, context, state)

@spec handle_event(term(), map(), map()) :: {:ok, map()}

Handles events for the table component.

init(props)

@spec init(map()) :: {:ok, map()}

Initializes the table component with the given props.

mount(state)

@spec mount(map()) :: {map(), list()}

Callback implementation for Raxol.UI.Components.Base.Component.mount/1.

render(assigns)

Callback implementation for Surface.Component.render/1.

render(state, context)

@spec render(map(), map()) :: any()

Renders the table component.

unmount(state)

@spec unmount(map()) :: map()

Callback implementation for Raxol.UI.Components.Base.Component.unmount/1.

update(arg, state)

@spec update(term(), map()) :: {:ok, map()}

Updates the table state based on the given message.