uitable

Create table user interface component

Syntax

uit = uitable

uit = uitable(Name,Value)

uit = uitable(parent)

uit = uitable(parent,Name,Value)

Description

uit = uitable creates a table user interface component in the current figure and returns the Table UI component object. If there is no figure available, MATLAB^® calls the figure function to create one.

uit = uitable(Name,Value) specifies property values of the table UI component using one or more name-value pair arguments.

example

uit = uitable(parent) creates the table in the specified parent container. The parent container can be a figure created with either the figure or uifigure function, or a child container such as a panel. Property values for uitable vary slightly depending on whether the app is created with the figure or uifigure function. For more information, see Name-Value Pair Arguments.

example

uit = uitable(parent,Name,Value) specifies the parent container and one or more property values.

Examples

collapse all

Display Table Array Data

Starting in R2018a, you can display table array data in a table UI component. (This type of data is supported only when the table UI component is in a figure created with the uifigure function. App Designer uses this type of figure for creating apps.)

Create table array t by calling the readtable function to read data from a file. Select four variables and 15 rows from t.

t = readtable('patients.xls');
vars = {'Age','Systolic','Diastolic','Smoker'};
t = t(1:15,vars);

Create a table UI component, and specify t as the data.

fig = uifigure;
uit = uitable(fig,'Data',t);

A table with four columns: "Age", "Systolic", "Diastolic", and "Smoker". The table is populated with data. The data in the "Smoker" column appears as checked or unchecked boxes.

Programmatically Update Table Data

Display and programmatically update table array data in a table UI component. (This type of data is supported only when the table UI component is in a figure created with the uifigure function. App Designer uses this type of figure for creating apps.)

Create a table array by reading in tsunami data from a file, and display a subset of the data in a table UI component.

t = readtable('tsunamis.xlsx');
vars = {'Year','MaxHeight','Validity'};
t = t(1:20,vars);
fig = uifigure;
uit = uitable(fig,'Data',t);

A table with three columns of tsunami data: the year of the tsunami, the maximum tsunami height in meters, and the validity of the tsunami (for example, "questionable tsunami" or "definite tsunami").

Update the validity of the tsunami in the first row by editing the Data property of the UI table.

uit.Data.Validity(1) = {'definite tsunami'};

A table with tsunami year, maximum height, and validity. The entry in the first row has a Validity value of "definite tsunami".

Convert the maximum height data from meters to feet by accessing and modifying the data in the MaxHeight column.

uit.Data.MaxHeight = uit.Data.MaxHeight*3.281;

A table with tsunami year, max height, and validity. The values in the MaxHeight column are in feet.

Enable and Code Response to Interactive Data Editing

Create an app that allows users to sort and edit table data, and that updates a data visualization when data is changed. (Interactive column sorting is supported only when the table UI component is in a figure created with the uifigure function. App Designer uses this type of figure for creating apps.)

First, create a program file called tsunamisData.m. Within the program file:

Create a table array by calling the readtable function.
Create a UI figure.
Create a sortable and editable table UI component to display in the figure. Store the table array to the component's Data property.
Create a bubble chart to visualize the tsunami data, where the coordinates of a bubble represent the latitude and longitude of the tsunami and the size of the bubble represents the maximum height.
Specify a DisplayDataChangedFcn callback that uses the DisplayData property to update the bubble chart when the app user sorts columns or edits cells in the table UI component.

function tsunamisData
    % Create table array
    t = readtable('tsunamis.xlsx');
    vars = {'Latitude','Longitude','MaxHeight'};
    t = t(1:20,vars);

    % Create UI figure
    fig = uifigure;
    fig.Position(3:4) = [722 360];

    % Create table UI component
    uit = uitable(fig);
    uit.Data = t;
    uit.ColumnSortable = true;
    uit.ColumnEditable = [false false true];
    uit.Position(3) = 290;
    uit.DisplayDataChangedFcn = @updatePlot;

    % Create bubble chart
    ax = uiaxes(fig);
    ax.Position(1) = 315;
    ax.XLabel.String = 'Longitude';
    ax.YLabel.String = 'Latitude';
    x = t.Longitude;
    y = t.Latitude;
    sz = t.MaxHeight;
    bubblechart(ax,x,y,sz)

        % Update the bubble chart when table data changes
        function updatePlot(src,event)
            t = uit.DisplayData;
            x = t.Longitude;
            y = t.Latitude;
            sz = t.MaxHeight;
            bubblechart(ax,x,y,sz)
        end

end

An app with a table displaying the Latitude, Longitude, and MaxHeight data for a number of tsunamis, and a bubble chart of the table data. The bubble chart plots the location of the tsunamis with Longitude on the x-axis, Latitude on the y-axis, and bubble size given by MaxHeight.

A sortable column displays arrows in the header when you hover your mouse over it. Sort the table by the maximum height of the tsunami.

The MaxHeight column of the tsunami data table is sorted in ascending order. The user's mouse cursor is on the MaxHeight column header, where an arrow pointing up is displayed next to the header text.

Edit the maximum height of the tsunami in the second row to be 30 meters by first double-clicking on the table cell, and then entering the new height. Notice how the bubble chart updates in response.

The cell in the second row and the MaxHeight column is selected, and the number 1 has been replaced with the number 30. The bubble chart bubble sizes have changed to reflect the new MaxHeight data.

Change Color of Specific Cells Based on Data

Starting in R2019b, you can style rows, columns, or cells of a table UI component using the uistyle and addStyle functions. (Styles are only supported when the table UI component is in a figure created with the uifigure function. App Designer uses this type of figure for creating apps.)

Style cells in a table UI component that contain missing values. In this case, add a red background color style to cells that have NaN values.

Read tsunami sample data into the workspace as a table array. Then, create a table UI component to display the data.

tdata = readtable('tsunamis.xlsx');
vars = {'Year','Month','Day','Hour', ...
        'MaxHeight','Cause','EarthquakeMagnitude'};
tdata = tdata(1:100,vars);

fig = uifigure('Position',[500 500 760 360]);
uit = uitable(fig);
uit.Position = [20 20 720 320];
uit.Data = tdata;
uit.RowName = 'numbered';

Use the ismissing function to get a logical array of the table elements that contain missing values. Find the row and column subscripts for the elements that have NaN values. Finally, create a red background color style and add it to the cells with NaN values in the table UI component.

styleIndices = ismissing(tdata);
[row,col] = find(styleIndices);

s = uistyle('BackgroundColor',[1 0.6 0.6]);
addStyle(uit,s,'cell',[row,col]);

Table with earthquake data. The cells with NaN are highlighted in red.

Programmatically Access Table Selection

Starting in R2021b, you can programmatically set and query which table elements are selected, and specify whether users can select cells, rows, or columns. (Programmatic selection is only supported when the table UI component is in a figure created with the uifigure function. App Designer uses this type of figure for creating apps.)

Using this feature, create an app that automatically plots data on a map when the user selects it in a table. First, create a program file called selectTsunamis.m. Within the program file:

Load the tsunami data by calling the readtable function.
Create a UI figure with a table UI component and a geographic bubble chart in a panel.
Configure the table UI component. Store the tsunami data in the Data property, and let users select multiple rows by setting the SelectionType and MultiSelect properties.
Specify a SelectionChangedFcn callback that updates the bubble chart when the app user changes the table selection. The function plots a bubble for each selected row, where the size of the bubble represents the maximum tsunami height.

function selectTsunamis
% Load data
T = readtable('tsunamis.xlsx');
vars = {'Latitude','Longitude','MaxHeight'};
T = T(1:20,vars);

% Create UI components
fig = uifigure('Position',[500 500 700 350]);
tbl = uitable(fig,'Position',[20 20 250 300]);
pnl = uipanel(fig,'Position',[285 20 400 300]);
geobubble(pnl,[],[]);

% Configure table
tbl.Data = T;
tbl.SelectionType = 'row';
tbl.Multiselect = 'on';
tbl.SelectionChangedFcn = @plotTsunami;

  % Plot tsunami data for each selected row
  function plotTsunami(src,event)
    rows = event.Selection;
    data = src.Data(rows,:);
    lat = data.Latitude;
    long = data.Longitude;
    ht = data.MaxHeight;
    geobubble(pnl,lat,long,ht);
  end
end

Run the selectTsunamis function, and select multiple table rows by holding down Ctrl while clicking. The plot updates with the tsunami data.

Figure window with a table and a geographic bubble chart. Multiple table rows are selected.

Programmatically Scroll to Table Row

Starting in R2021a, you can programmatically scroll to a row, column, or cell of a table UI component using the scroll function. (Programmatic scrolling is only supported when the table UI component is in a figure created with the uifigure function. App Designer uses this type of figure for creating apps.)

Read sample patient data into the workspace as a table array. Then, create a table UI component to display the data.

tdata = readtable('patients.xls');
vars = {'Age','Systolic','Diastolic','Smoker'};
tdata = tdata(1:40,vars);

fig = uifigure;
uit = uitable(fig,'Data',tdata);
uit.RowName = 'numbered';

Table with patient data in a UI figure window. The table rows are numbered, and the table is scrolled to the top.

Scroll to the 25th row of the table.

scroll(uit,'row',25)

Table with patient data in a UI figure window. The table is scrolled so that row 25 is at the top of the visible data.

Display Array of Numbers

Create a table UI component that displays a 10-by-3 array of random integers. The Data property specifies the values to display, and the Position property specifies the location and size of the table within the figure.

f = figure;
uit = uitable(f,'Data',randi(100,10,3),'Position',[20 20 262 204]);

Table with ten rows and three columns of numerical data.

Display Mixed Data Types

Table UI components can accommodate a mixture of different data types across the columns.

Create an empty Table UI component.

f = figure;
uit = uitable(f);

Set the Data property to populate the data as a cell array that contains a mixture of different types. Then set the Position property to adjust the location and size of the table to fit the data.

d = {'Male',52,true;'Male',40,true;'Female',25,false};
uit.Data = d;
uit.Position = [20 20 258 78];

Table with three rows and three columns. The first column contains text, the second column contains numerical data, and the third column contains check boxes. The check boxes in the first and second rows are selected.

Set the ColumnName property to change the column headings to descriptive names. Set the ColumnEditable property to true so that users can edit the data in the UI. When a user changes a value in the UI, the Data property updates to reflect that change.

uit.ColumnName = {'Gender','Age','Authorized'};
uit.ColumnEditable = true;

Table with three rows and three columns. Each column has a column name above the data.

Input Arguments

collapse all

`parent` — Parent container
`Figure` object (default) | `Panel` object | `Tab` object | `ButtonGroup` object | `GridLayout` object

Parent container, specified as a figure created with either the figure or uifigure function, or a child container:

Panels, tabs and button groups can be containers in either type of figure.
Grid layouts can be containers only in figures created with the uifigure function.

Name-Value Arguments

Example: uitable(fig,'Data',[1 2 3; 4 5 6])

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments as Name1,Value1,...,NameN,ValueN.

Note

The properties listed here are a subset of the available properties. For the full list, see Table Properties.

`Data` — Table data
table array | numeric array | logical array | cell array | string array | ...

Table data, specified as one of the following types of array:

Table array (uifigure-based apps only) — Displays any combination of data types that table arrays support, such as datetime, duration, and categorical.
Numeric array — Displays numeric values such as double or single.
Logical array — Displays check boxes. true values correspond to selected boxes, whereas false values display cleared boxes.
Cell array — Displays any combination of numeric, logical, or character array values.
String array — Displays characters and text.
Cell array of character vectors — Displays characters and text.

To prevent warnings or NaN values that display when users enter invalid data into an editable cell, write a CellEditCallback function to convert the data to the appropriate type. When a user edits a cell, the Data property updates.

Specify a Table Array

In App Designer and apps created using the uifigure function, you can specify the Data property as a table array. Table arrays provide a convenient way to store tabular data as a MATLAB variable. The table, readtable, and array2table functions create table arrays. By contrast, the uitable function creates a Table UI component (a user interface component for an app).

When you specify the Data property of a Table UI component as a table array, then MATLAB sets the format of the Table UI component automatically based on the values in the table array:

By default, the column names displayed in the app match the VariableNames property of the table array. Changing the ColumnName property of the Table UI component updates the UI, but it does not update the variable names in the table array.
By default, the row names displayed in the app match the RowName property of the table array. Changing the RowName property of the Table UI component updates the UI, but it does not update the row names in the table array.
The data type of each table array variable controls formatting for the corresponding column in the app. If you try to set the ColumnFormat property, MATLAB returns a warning.

For more information on displaying table array data, see Table Array Data Types in App Designer Apps.

Specify Numeric, Logical, Cell, String Array, or Cell Array of Character Vectors

Use the ColumnFormat property to specify the format for data that is a numeric, logical, cell, or string array, or a cell array of character vectors. If data is edited and results in a mismatch between the data type of the data and the ColumnFormat property, MATLAB converts the data or displays a warning. See Data Display of Editable Columns in the ColumnFormat property description for more information.

`ColumnWidth` — Width of table columns
`'auto'` (default) | `'fit'` | `'1x'` | 1-by-`n` cell array

Width of table columns, specified as 'auto' or as a 1-by-n cell array of character vectors, strings, and numeric values. In uifigure-based apps, you can additionally specify the column width as '1x' or 'fit'.

Automatic widths — Specify 'auto' to have MATLAB calculate the widths of the columns automatically using several factors, one of which is the ColumnName property value.
Fit widths to content (uifigure-based apps only) — Specify a value of 'fit' to configure columns to strictly adjust widths to fit column names and data. This setting allows narrower columns than 'auto' does.
Uniform widths (uifigure-based apps only) — Specify a value of '1x' to make all columns the same width, dividing the available space equally.
Fixed widths — Specify a cell array of numeric values that define the column widths in pixel units.
Combinations — You can combine fixed and variable column widths in a cell array. Each element in the cell array corresponds to a column in the table. If the cell array you specify has fewer values than the number of columns, then the columns with no specified value keep the default value of 'auto'. If the array has more values than the number of columns, MATLAB ignores the extra values.
Weighted variable widths (uifigure-based apps only) — Specify a cell array with character vectors or strings composed of a number concatenated with an 'x' (for example, '2x', '3x', etc.). The x-factor of each column sets that column width proportionally with respect to the others, with consideration for the remaining space in the UI table.

Example: uit = uitable(uifigure,'ColumnWidth','auto','Data',[1 2 3;4 5 6])

Example: uit = uitable(uifigure,'ColumnWidth','fit','Data',[1 2 3;4 5 6])

Example: uit = uitable(uifigure,'ColumnWidth',{64,60,40},'Data',[1 2 3;4 5 6])

Example: uit = uitable(uifigure,'ColumnWidth',{'2x','1x','1x'},'Data',[1 2 3;4 5 6])

Example: uit = uitable(uifigure,'ColumnWidth',{64,"auto",40},'Data',[1 2 3;4 5 6])

Example: uit = uitable(uifigure,'ColumnWidth',{'fit','1x','3x'},'Data',[1 2 3;4 5 6])

`ColumnEditable` — Ability to edit column cells
`[]` (default) | logical 1-by-`n` array | logical scalar

Ability to edit column cells, specified as:

An empty logical array ([]) — No columns are editable.
A logical 1-by-n array — This array specifies which columns are editable. The value of n is equal to the number of columns in the table. Each value in the array corresponds to a table column. A value of true in the array makes the cells in that column editable. A value of false makes the cells in that column uneditable. If the array has more values than the number of columns, MATLAB ignores the excess values. If the array has fewer values than the number of columns, then the columns with no specified value are not editable.
A logical scalar — The entire table is editable or uneditable.

When a user edits a cell, the Data property updates.

Example: uit = uitable(uifigure,'Data',rand(10,3),'ColumnEditable',[false true true])

Example: uit = uitable(uifigure,'Data',rand(10,3),'ColumnEditable',false)

To enable users to interact with the controls in table columns that contain check boxes or pop-up menus, set the ColumnEditable property to true.

If the Data property is a table array, then any variables that are multicolumn or contain non-editable data types, like duration, are not editable in the running app even when the ColumnEditable property is true. Table array variables that contain mixed data types in a cell array are editable in the running app, as long as the data types are editable.

`CellEditCallback` — Cell edit callback function
function handle | cell array | character vector

Cell edit callback function, specified as one of these values:

A function handle.
A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.
A character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

Use this callback function to perform calculations or validate input when the app user changes the contents of a table cell.

This callback function can access specific information about the user’s interaction with the cell (such as the cell indices). MATLAB passes this information in a CellEditData object as the second argument to your callback function. In App Designer, the argument is called event. You can query the object properties using dot notation. For example, event.Indices returns the indices of the selected cell. The CellEditData object is not available to callback functions specified as character vectors.

The following table describes properties of the CellEditData object.

Property	Description
`Indices`	This is a 1-by-2 array containing the row and column indices of the cell the user edited in the running app. When a column is sorted, `Indices` returns the original 1-by-2 array of a cell before it was sorted—`DisplayIndices` returns the new location of the edited cell that displays visually in the sorted table.
`DisplayIndices`	This is a 1-by-2 array containing the row and column indices corresponding to the location of the edited cell in the display of the sorted table. If a user does not sort columns, then `DisplayIndices` has the same content as the `Indices` property.
`PreviousData`	This is the previous cell data. The default is an empty matrix, `[]`.
`EditData`	This is the user-entered value.
`NewData`	This is the value that MATLAB wrote to the `Data` property array. The `NewData` property is empty if MATLAB detects an error in the user-entered data.
`Error`	This is the error message returned if MATLAB detects an error in the user-entered data. The `Error` property is empty when MATLAB successfully writes the value to the `Data` property. If the `Error` property is not empty, then the `CellEditCallback` can display the message, or it can attempt to fix the problem.
`Source`	Component executing the callback.
`EventName`	`'CellEdit'`.

When the user edits a table cell, MATLAB performs these steps:

Tries to store the new value into the Data property of the table
Calls the CellEditCallback function (if it exists)

If the value results in an error and there is no CellEditCallback function, then the cell data reverts to its previous value and no error displays.

For more information about writing callbacks, see Callbacks in App Designer.

`Position` — Location and size of table
`[left bottom width height]`

Location and size of the table, specified as a four-element vector of the form [left bottom width height]. This table describes each element in the vector.

Element	Description
`left`	Distance from the inner left edge of the parent container to the outer left edge of the table
`bottom`	Distance from the inner bottom edge of the parent container to the outer bottom edge of the table
`width`	Distance between the right and left outer edges of the table
`height`	Distance between the top and bottom outer edges of the table

All measurements are in units specified by the Units property.

The Position values are relative to the drawable area of the parent container. The drawable area is the area inside the borders of the container and does not include the area occupied by decorations such as a menu bar or title.

`Units` — Units of measurement
`'pixels'` | `'normalized'` | `'inches'` | `'centimeters'` | `'points'` | ...

Units of measurement, specified as one of the values in this table.

Units Value	Description
`'pixels'` (default)	Distances in pixels are independent of your system resolution on Windows^® and Macintosh systems: On Windows systems, a pixel is 1/96th of an inch. On Macintosh systems, a pixel is 1/72nd of an inch. On Linux^® systems, the size of a pixel is determined by your system resolution.
`'normalized'`	These units are normalized with respect to the parent container. The lower-left corner of the container maps to `(0,0)` and the upper-right corner maps to `(1,1)`.
`'inches'`	Inches.
`'centimeters'`	Centimeters.
`'points'`	Points. One point equals 1/72nd of an inch.

The recommended value is 'pixels', because most MATLAB app building functionality measures distances in pixels. You can create a table that rescales based on the size of the parent container by parenting the table to a grid layout manager created using the uigridlayout function. For more information, see Lay Out Apps Programmatically.

`figure`-Based Apps

For tables in apps created using the figure function, the default value of Units is 'normalized'.

In addition, you can specify Units as 'characters'. Character units are based on the default uicontrol font of the graphics root object:

Character width = width of the letter x.
Character height = distance between the baselines of two lines of text.

To access the default uicontrol font, use get(groot,'defaultuicontrolFontName') or set(groot,'defaultuicontrolFontName').

Version History

Introduced in R2008a

expand all

R2022a: Rearrange columns interactively

Specify the ability to interactively rearrange table columns in an app by using the ColumnRearrangeable property. In a table UI component with the ColumnRearrangeable value set to 'on', rearrange table columns in the app by clicking and dragging the column header.

In App Designer and apps created using the uifigure function, you can program an app to respond when a user rearranges table columns by creating a DisplayDataChangedFcn callback function.

For more information, see Table Properties.

R2021b: Set, query, and configure options for table selection

Use properties to configure selection options for table UI components.

Set and query the table selection using the Selection property.
Specify whether a user can select table cells, rows, or columns using the SelectionType property.
Specify whether a user can select single or multiple table elements using the Multiselect property.
Update your app whenever a user selects table data by specifying a SelectionChangedFcn callback.

Selection options in table UI components are supported only in App Designer apps and in figures created with the uifigure function.

For more information, see Table Properties.

uitable

Syntax

Description

Examples

Display Table Array Data

Programmatically Update Table Data

Enable and Code Response to Interactive Data Editing

Change Color of Specific Cells Based on Data

Programmatically Access Table Selection

Programmatically Scroll to Table Row

Display Array of Numbers

Display Mixed Data Types

Input Arguments

`parent` — Parent container
`Figure` object (default) | `Panel` object | `Tab` object | `ButtonGroup` object | `GridLayout` object

Name-Value Arguments

`Data` — Table data
table array | numeric array | logical array | cell array | string array | ...

Specify a Table Array

Specify Numeric, Logical, Cell, String Array, or Cell Array of Character Vectors

`ColumnWidth` — Width of table columns
`'auto'` (default) | `'fit'` | `'1x'` | 1-by-`n` cell array

`ColumnEditable` — Ability to edit column cells
`[]` (default) | logical 1-by-`n` array | logical scalar

`CellEditCallback` — Cell edit callback function
function handle | cell array | character vector

`Position` — Location and size of table
`[left bottom width height]`

`Units` — Units of measurement
`'pixels'` | `'normalized'` | `'inches'` | `'centimeters'` | `'points'` | ...

`figure`-Based Apps

Version History

R2022a: Rearrange columns interactively

R2021b: Set, query, and configure options for table selection

See Also

Functions

Properties

Topics

uitable

Syntax

Description

Examples

Display Table Array Data

Programmatically Update Table Data

Enable and Code Response to Interactive Data Editing

Change Color of Specific Cells Based on Data

Programmatically Access Table Selection

Programmatically Scroll to Table Row

Display Array of Numbers

Display Mixed Data Types

Input Arguments

parent — Parent container Figure object (default) | Panel object | Tab object | ButtonGroup object | GridLayout object

Name-Value Arguments

Data — Table data table array | numeric array | logical array | cell array | string array | ...

Specify a Table Array

Specify Numeric, Logical, Cell, String Array, or Cell Array of Character Vectors

ColumnWidth — Width of table columns 'auto' (default) | 'fit' | '1x' | 1-by-n cell array

ColumnEditable — Ability to edit column cells [] (default) | logical 1-by-n array | logical scalar

CellEditCallback — Cell edit callback function function handle | cell array | character vector

Position — Location and size of table [left bottom width height]

Units — Units of measurement 'pixels' | 'normalized' | 'inches' | 'centimeters' | 'points' | ...

figure-Based Apps

Version History

R2022a: Rearrange columns interactively

R2021b: Set, query, and configure options for table selection

See Also

Functions

Properties

Topics

`parent` — Parent container
`Figure` object (default) | `Panel` object | `Tab` object | `ButtonGroup` object | `GridLayout` object

`Data` — Table data
table array | numeric array | logical array | cell array | string array | ...

`ColumnWidth` — Width of table columns
`'auto'` (default) | `'fit'` | `'1x'` | 1-by-`n` cell array

`ColumnEditable` — Ability to edit column cells
`[]` (default) | logical 1-by-`n` array | logical scalar

`CellEditCallback` — Cell edit callback function
function handle | cell array | character vector

`Position` — Location and size of table
`[left bottom width height]`

`Units` — Units of measurement
`'pixels'` | `'normalized'` | `'inches'` | `'centimeters'` | `'points'` | ...

`figure`-Based Apps