Main Content

uitable

Create table user interface component

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

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.

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.

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 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.

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 yellow 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 yellow 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]);

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';

Scroll to the twenty-fifth row of the table.

scroll(uit,'row',25)

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 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];

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;

Input Arguments

collapse all

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 Pair 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.

You can set Table properties using Name-Value pair arguments.

  • For a list of properties available for apps created with the uifigure function or in App Designer, see Table Properties.

  • For a list of properties available for apps created with the figure function, see Table Properties.

Introduced in R2008a