Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Section
Column
width80%
Panel
bgColor#f6f6f6
titleBGColor#333333
borderStylesolid
titleTables
borderColor#cccccc
titleColorwhite

Purpose: Demonstrates recommended table layout, styling, and configuration for use with tabular data.

Category: Tables, Tabular Data, Datatables

Related jiras:

JIRA
columnskey,summary,type,created,updated,due,assignee,reporter,priority,status,resolution
serverKuali: Jira
serverIdbe3acfec-fcc2-335b-8051-b2b053a39956
keyUXI-283
JIRA
columnskey,summary,type,created,updated,due,assignee,reporter,priority,status,resolution
serverKuali: Jira
serverIdbe3acfec-fcc2-335b-8051-b2b053a39956
keyUXI-205

Process Phase:

  •  UXI JIRA Created (insert link above)
  •  Component Specification draft complete
  •  UXI code review complete
  •  Reconcile with UIM and KRAD existing designs
  •  Conduct user testing (if needed)
  •  Routed for review with Kuali UX Working Group and UX/KRAD Working Group
  •  Reviewed with KAI
  •  Rice JIRA Created (in KULRICE Project)
  •  KRAD Implementation complete
  •  Component released (insert rice release version below)

Version: 1.0

...

The objective of tables is to present information in a way that preserves relationships within the information even when users cannot see the table or the presentation format is changed. Information is considered tabular when logical relationships among text, numbers, images, or other data exist in two dimensions (vertical and horizontal). These relationships are represented in columns and rows, and the columns and rows must be recognizable in order for the logical relationships to be perceived.

Datatables are tables that have been enhanced with the jquery.datatables.js plugin, which allows column ordering and sorting, data filtering, and table pagination. Tables by themselves are fairly accessible, but consideration should be taken when enhancing them with the datatables plugin.

This document provides requirements and recommendations for markup and styles, as well as accessibility information and considerations.

...

Deck of Cards
idcomponent_details
startHiddenfalse
Card
iddesktop-usage
defaulttrue
labelDesktop Usage

Desktop Usage

Tabular collection with extended details/information

Quick summary of features:

  • Tables use Bootstrap 3 classes as a base; additional KRAD classes may be applied to override or extend what Bootstrap offers:
    • table
    • table-bordered
    • table-condensed
  • A single table header row <th> should go at the very top of the table
  • Sections within a table received a colspan <td> with the class of ".row-separator". This will give it a gray background with bolded text as seen above.
    • Used to separate groups of content within a table collection
  • The last column in each row is used for actions and buttons. The actions affect the row which the button is in.
  • "Details" button reveals a modal with the option to edit tabular data as well as extended/additional data for each row.
    • Making changes within the modal will refresh/redraw the page upon Save so that other details can use updated data.

When to use this component:

  • Whenever tabular data needs to be displayed in column/row fashion
  • When tabular data can be grouped into related sections
  • When more information for the entry needs to be present but not necessarily visible

Tabular collection with inline editing

Quick summary of features:

  • Tables use on Bootstrap 3 classes
    • table
    • table-bordered
    • table-condensed
  • A single table header row <th> should go at the very top of the table
  • The last column in each row is used for actions and buttons. The actions affect the row which the button is in.
  • "Edit" button makes cell data editable.
    • When editing row data, available actions are "Save" and "Cancel".
      • "Save" would save the edited data without refreshing/redrawing the page.
      • "Cancel" would back out of the edit process and replace previously saved data.

When to use this component:

  • When tabular data needs to be quickly edited, and
  • When all pertinent data fields will fit within a single row
  • When seeing nearby tabular data is necessary or makes editing another rows' data easier or more efficient

Deleting entries and rows

The "trash can" icon to the far right of each row serves as a method to delete the entry or row of data. When clicked, users may or may not be prompted to confirm the deletion. If no prompt is provided, there must be a way to reverse the action (perhaps as an "undo" link in the confirmation). If a prompt is provided and the user confirms the deletion, the entire row is removed from the table. jQuery offers the $.fadeOut() method to make this action more visually graceful.

A table with the second entry under "2013" about to be deleted. The icon is hovered.

The delete button clicked and the row/entry beginning to fade away.

The row has been deleted.

Adding entries to a collection

When adding items to a collection (or table) we place two main action buttons at the top and bottom of the collection allowing for easy access to manipulate the data whether one is at the top of the table or at the bottom. The bottom button is extremely helpful in situations where a collection is lengthy.

Confirmation and feedback messaging

Confirming before a row is to be deleted. Clicking "OK" here would return true and delete the row. Clicking "Cancel" would return return false and cancel the deletion.

Example of a success or validation message indicating the deletion was a success.

Datatable with column sorting

Image Added

Quick summary of features:

  • Simply add .datatable to any table to add this functionality. The plugin adds column sorting, filtering, and pagination automatically.
  • The fallback is a table that looks and acts like a normal table.

When to use this component:

  • Use whenever tables or collections have a lot of entries that when broken up into pages, are easier to digest.
  • Use when sorting a column aids in findability.
Card
idresponsive-usage
labelResponsive Usage

Responsive Usage

Add .uif-responsive to the table to make it responsive.

Example of a responsive table

Quick summary of features:

  • On tablets and mobile devices, tables are automatically restructured to a more vertical layout to better suit the device display.
    • Individual <tr>'s become their own "containers".
    • Any <td> within the <tr> can become the main "heading" for the new container (the bolded, larger item as seen above).
  • In cases where selections are made, the entire item becomes clickable, indicated with a ">" to the right side of the row.

When to use this component:

  • If the responsive class is added to the table then there's nothing else you need to do!
Card
idworking-content
labelWorking with content

Working with content (desktop and mobile views)

Desktop

Adding, editing, and deleting content

Actions, such as adding, editing, and deleting content in tabular data, are usually found towards the right-side of the table.

Adding entries to a collection should be performed via a button placed both above and below the table. This allows for quick and easy additions regardless of where you are on the page scroll.

Editing and deleting entries in a collection are also performed via buttons, but these are icon buttons usually located in the last column of the entry. The delete button should use the .icon-delete icon class within a button. The text label may or may not be hidden using .sr-only. We advise that it is hidden to glean as much room within the table as possible. Do ensure that a text label is present though, for accessibility purposes.

The edit button should use the .icon-edit icon class within a button. The text label may or may not be hidden using .sr-only. We advise that the text label is hidden to utilize the table space most efficiently, but we do request the text label be present.

Entering into 'edit mode' removes the Delete and Edit buttons, swapping them out with Save and Cancel buttons

Viewing additional details

Some data table entries have more data attached to them than will fit nicely in the table. In cases like this, we show the most relevant data (columns) and include a "Details" button. Clicking the "Details" button opens a modal which contains all of the data attached to that particular entry. It may or may not be editable, and the data may even be organized into tabs or additional data tables.

Mobile

Adding, editing, and deleting content

Adding, editing, and deleting entries from collections works just like on the desktop resolution. The action buttons will be at the bottom of each entry. Tapping them will perform the same action in very much the same way.

Viewing additional details

Tapping the entry title, usually at the top of the entry in responsive views, will open the details for that entry.

Card
iddemos
labelDemos

Demos

HTML

Below is basic table markup showing "Edit" and "Delete" buttons in the rightmost column. To add responsive functionality to tables, simply add a class of "uif-responsive" to the table.

Code Block
linenumberstrue
languagexml
firstline1
<table class="table table-bordered table-condensed">
    <caption>Ford vehicles by year</caption>
    <thead>
		<tr>
			<td colspan="4">
				<div class="btn-group">
					<button class="btn btn-default btn-sm"><span class="icon icon-add"></span> Add to collection</button>
				</div>
			</td>
		</tr>
        <tr>
            <th scope="col">Make</th>
            <th scope="col">Model</th>
            <th scope="col">Color</th>
            <td scope="col" class="uif-action-column"></td>
        </tr>
    </thead>
    <tbody>
        <tr class="row-separator">
            <td colspan="4">2014</td>
        </tr>
        <tr>
            <td>Ford</td>
            <td>Escort</td>
            <td>Blue</td>
            <td>
                <button type="button" class="btn btn-xs btn-default">Edit</button>
                <button type="button" class="btn btn-xs btn-default"><span class="sr-only">Delete</span><i class="glyphicon glyphicon-trash"></i></button>
            </td>
        </tr>
        <tr class="row-separator">
            <td colspan="4">2013</td>
        </tr>
        <tr>
            <td>Ford</td>
            <td>Escort</td>
            <td>Red</td>
            <td>
                <button type="button" class="btn btn-xs btn-default">Edit</button>
                <button type="button" class="btn btn-xs btn-default"><span class="sr-only">Delete</span><i class="glyphicon glyphicon-trash"></i></button>
            </td>
        </tr>
        <tr>
            <td>Ford</td>
            <td>Escort</td>
            <td>Green</td>
            <td>
                <button type="button" class="btn btn-xs btn-default">Edit</button>
                <button type="button" class="btn btn-xs btn-default"><span class="sr-only">Delete</span><i class="glyphicon glyphicon-trash"></i></button>
            </td>
        </tr>
        <tr>
            <td>Ford</td>
            <td>Escort</td>
            <td>Blue</td>
            <td>
                <button type="button" class="btn btn-xs btn-default">Edit</button>
                <button type="button" class="btn btn-xs btn-default"><span class="sr-only">Delete</span><i class="glyphicon glyphicon-trash"></i></button>
            </td>
        </tr>
        <tr class="row-separator">
            <td colspan="4">2012</td>
        </tr>
        <tr>
            <td>Ford</td>
            <td>Escort</td>
            <td>Green</td>
            <td>
                <button type="button" class="btn btn-xs btn-default">Edit</button>
                <button type="button" class="btn btn-xs btn-default"><span class="sr-only">Delete</span><i class="glyphicon glyphicon-trash"></i></button>
            </td>
        </tr>
        <tr>
            <td>Ford</td>
            <td>Escort</td>
            <td>Blue</td>
            <td>
                <button type="button" class="btn btn-xs btn-default">Edit</button>
                <button type="button" class="btn btn-xs btn-default"><span class="sr-only">Delete</span><i class="glyphicon glyphicon-trash"></i></button>
            </td>
        </tr>
    </tbody>
	<tfoot>
		<tr>
			<td colspan="4">
				<div class="btn-group">
					<button class="btn btn-default btn-sm"><span class="icon icon-add"></span> Add to collection</button>
				</div>
			</td>
		</tr>
	</tfoot>
</table>

Code example utilizing the datatable plugin

To instantiate a table to act as a datatable, you can add the .datatable class to the table, or manually invoke it with jQuery $(el).DataTable();

Code Block
linenumberstrue
languagexml
firstline1
<table class="table table-bordered table-condensed datatable">
    <caption>Ford vehicles by year</caption>
    <thead>
		<tr>
			<td colspan="4">
				<div class="btn-group">
					<button class="btn btn-default btn-sm"><span class="icon icon-add"></span> Add to collection</button>
				</div>
			</td>
		</tr>
        <tr>
            <th scope="col">Make</th>
            <th scope="col">Model</th>
            <th scope="col">Color</th>
            <td scope="col" class="uif-action-column"></td>
        </tr>
    </thead>
    <tbody>
        <tr class="row-separator">
            <td colspan="4">2014</td>
        </tr>
        <tr>
            <td>Ford</td>
            <td>Escort</td>
            <td>Blue</td>
            <td>
                <button type="button" class="btn btn-xs btn-default">Edit</button>
                <button type="button" class="btn btn-xs btn-default"><span class="sr-only">Delete</span><i class="glyphicon glyphicon-trash"></i></button>
            </td>
        </tr>
        <tr class="row-separator">
            <td colspan="4">2013</td>
        </tr>
        <tr>
            <td>Ford</td>
            <td>Escort</td>
            <td>Red</td>
            <td>
                <button type="button" class="btn btn-xs btn-default">Edit</button>
                <button type="button" class="btn btn-xs btn-default"><span class="sr-only">Delete</span><i class="glyphicon glyphicon-trash"></i></button>
            </td>
        </tr>
        <tr>
            <td>Ford</td>
            <td>Escort</td>
            <td>Green</td>
            <td>
                <button type="button" class="btn btn-xs btn-default">Edit</button>
                <button type="button" class="btn btn-xs btn-default"><span class="sr-only">Delete</span><i class="glyphicon glyphicon-trash"></i></button>
            </td>
        </tr>
        <tr>
            <td>Ford</td>
            <td>Escort</td>
            <td>Blue</td>
            <td>
                <button type="button" class="btn btn-xs btn-default">Edit</button>
                <button type="button" class="btn btn-xs btn-default"><span class="sr-only">Delete</span><i class="glyphicon glyphicon-trash"></i></button>
            </td>
        </tr>
        <tr class="row-separator">
            <td colspan="4">2012</td>
        </tr>
        <tr>
            <td>Ford</td>
            <td>Escort</td>
            <td>Green</td>
            <td>
                <button type="button" class="btn btn-xs btn-default">Edit</button>
                <button type="button" class="btn btn-xs btn-default"><span class="sr-only">Delete</span><i class="glyphicon glyphicon-trash"></i></button>
            </td>
        </tr>
        <tr>
            <td>Ford</td>
            <td>Escort</td>
            <td>Blue</td>
            <td>
                <button type="button" class="btn btn-xs btn-default">Edit</button>
                <button type="button" class="btn btn-xs btn-default"><span class="sr-only">Delete</span><i class="glyphicon glyphicon-trash"></i></button>
            </td>
        </tr>
    </tbody>
	<tfoot>
		<tr>
			<td colspan="4">
				<div class="btn-group">
					<button class="btn btn-default btn-sm"><span class="icon icon-add"></span> Add to collection</button>
				</div>
			</td>
		</tr>
	</tfoot>
</table>

CSS

And the custom styles for this table.

Code Block
linenumberstrue
languagecss
firstline1
.row-separator {
    background: #f2f2f2;
    font-weight: bold;
}
 
/* You may hide captions off-screen, but then they aren't as useful.
 * We recommend showing the captions, maybe styling them to look nice.
 */
table caption {
    position: absolute;
    left: -9999em;
}

JSFiddle

View this markupexamples of normal tables on JSFiddle.
View an example of a datatable on JSFiddle. This example also demonstrates proper accessibility.
Note: Markup on JSFiddle also includes markup for tables with only horizontal lines, as well as tables without sections. 

KRAD Library

View this component in the current KRAD component library.

Card
idwhen-to-use
labelWhen to use

When to use

Pattern use cases

UseScenarioDescription
NoDesign, layout and positioningTables are not to be used for layout, positioning or other design tasks.
YesCollectionsTables and datatables are to be used for collections that have a tabular format (rows and columns).
YesCollection within a pageUse datatables to organize data on a page.
YesCollection within a modalYou can also use datatables to organize data within a modal.
NoSummary summary=""We advise against using the summary attribute.
YesCaption <caption>...</caption>Use a caption when using a table that is not a datatable (e.g., a collection of read-only content).
Card
idaccessibility
labelAccessibility Considerations
nextAfter0
Section

Accessibility Considerations

Required Level of Compliance:

In order to meet WCAG 2.0 guidelines, these are some considerations that may apply to this component:

1.3.1 Tables are used for tabular data. Where necessary, data cells are associated with their headers. Data table captions and summaries are used where appropriate.

H73 Use the caption to give an overview of the data table. The caption may be positioned off-screen using CSS to hide it visually. Alternatively, the summary attribute may be used to give a brief description of the table data. However, the summary is not included in the HTML5 spec and isn't well supported.
H63 Use the scope attribute to associate header cells and data cells.
H43 Use IDs and header attributes to associate data cells with header cells. (not recommended)
H73 The summary attribute provides an overview of the table structure.

Table summary, table caption

The summary attribute for tables gives an overview of the table structure, but isn't well supported and is not included in the HTML5 specification. WebAIM advises against using them.

Table captions are another story. While not required, captions can be very helpful. Please see the "when to use" section above when determining when to use captions.

Two-dimensional, three-dimensional, and responsive tables

Two-dimensional (2D) tables - those with a single column:row relationship - are preferred. Minimize or avoid three-dimensional (3D) tables as they get complex and do not read properly in Apple iOS. Avoid responsive tables.

Behavior without scripting

:

If javascript is turned off, this component should behave normally, as a table would expect. The table should not rely on any scripting to function, however scripting may add additional functionality as needed.d

Accessibility Resources:

Column sorting, filtering, and pagination

The enhanced features that come with the plugin, like column sorting, data filtering, and pagination, are all accessible out of the box. Activating a column header to sort should be indicated aurally, including which direction the data is being sorted.

The plugin should automatically make the table a live region so filtering will aurally announce the updated content results within it, but you'll want to double check to ensure it works.

Finally, pagination controls should be after the first page of content and should announce the total number of results in the collection along with which page the user is on and how many results are on that particular page. Activating a pagination control should update the already live-region table, announcing the updates appropriately.

Accessibility Resources

W3 HTML Validator
WebAim WAVE 

Card
idkeyboard-shortcuts
labelKeyboard Shortcuts

Keyboard Shortcuts

None

Card
idcomponent_discussion
titleResearch and Discussion
labelResearch & Discussion

Research and Discussion

Includes usability research findings and recommendations, information from the UIM discussion page, links, chapters, articles, etc that supports the design decision.