@nomadx/table
<nomadx-table>
is a set of vanilla web-components to simplify the creation of accessible, responsive HTML tables.
For Developers:
The <nomadx-table>
component automatically creates rich HTML tables from your dataset. The flexible <nomadx-table-data>
component allows you to generate tables through simple markup or bind data from Javascript, supporting CSV or TSV format, Markdown, JSON Arrays, and 2D Arrays.
Here's a minimal example using CSV format in your markup:
<nomadx-table>
<nomadx-table-data>
Column A, Column B, Column C, Column D
0, true, Hello, World!
2, false, Foobar, Bazbing
</nomadx-table-data>
</nomadx-table>
By specifying attributes on the <nomadx-table>
element, you can control which columns are sortable
, which are fixed-width
(the default is responsive), if the table is striped
, and more. More information in the API section below.
For Your Users:
All Nomadx elements come pre-baked with a11y
best practices like roving focus, keyboard-only navigation, and screen-reader support. Our goal is to make tables that work exactly like you'd expect them to, so we followed the W3C's Best Practices and then added even more functionality (like beautiful clipboard support, meta sequences for keyboards, and more.)
Using this component
Script tag
- Publish to NPM
- Drop this
<script src='https://unpkg.com/@nomadx/table@0.0.1/dist/index.js'></script>
in the head of your index.html - Then you can use the element anywhere in your template, JSX, html etc
Node Modules
- Run
npm install @nomadx/table --save
- Put a script tag similar to this
<script src='node_modules/@nomadx/table/dist/index.js'></script>
in the head of your index.html - Then you can use the element anywhere in your template, JSX, html etc
In a stencil-starter app
- Run
npm install @nomadx/table --save
- Add an import to the npm packages
import '@nomadx/table';
- Then you can use the element anywhere in your template, JSX, html etc
Data Input
via Markup
<!-- CSV Format -->
<nomadx-table>
<nomadx-table-data>
Column A, Column B, Column C, Column D
0, true, Hello, World!
2, false, Foobar, Bazbing
</nomadx-table-data>
</nomadx-table>
<!-- TSV Format -->
<nomadx-table>
<nomadx-table-data>
Column A	Column B	Column C	Column D
0	true	Hello	World!
2	false	Foobar	Bazbing
</nomadx-table-data>
</nomadx-table>
<!-- GFM Table Format -->
<nomadx-table>
<nomadx-table-data>
| Column A | Column B | Column C | Column D |
|----------|----------|----------|----------|
| 0 | true | Hello | World! |
| 2 | false | Foobar | Bazbing |
</nomadx-table-data>
</nomadx-table>
<!-- 2D Array or JSON Array via JSX -->
<nomadx-table>
<nomadx-table-data data={myData}> </nomadx-table-data>
</nomadx-table>
via Javascript
const tableA = document.querySelector('nomadx-table-data#table-a');
const my2DArray = [
['Column A', 'Column B', 'Column C', 'Column D'],
[0, true, 'Hello', 'World!'],
[2, false, 'Foobar', 'Bazbing']
]
tableA.onComponentReady().then(() => {
tableA.data = my2DArray;
})
const tableB = document.querySelector('nomadx-table-data#table-b');
const myJSONArray = [
{ 'Column A': 0, 'Column B': true, 'Column C': 'Hello', 'Column D': 'World!' }
{ 'Column A': 2, 'Column B': false, 'Column C': 'Foobar', 'Column D': 'Bazbing' }
]
tableB.onComponentReady().then(() => {
tableB.data = myJSONArray;
})
API
<nomadx-table>
Attributes
Attribute | Value | Default |
---|---|---|
name | string | "" |
striped | present|'true'|'false' | false |
sortable | present|'true'|'false'|'0 1 2 3 ...' | false |
fixed-width | present|'true'|'false'|'0 1 2 3 ...' | false |
Name
Setting a name for the table is highly reccommended for accessibility. This will automatically be read to any users interacting with your project via assistive technology.
Note that there is no need to include the word "Table"
in the name, because screen readers will automatically announce that the element is a table.
<nomadx-table name="Orders"></nomadx-table>
Striped
Nomadx tables are not striped by default, but this can easily be enabled by including a striped
attribute.
<nomadx-table striped></nomadx-table> <!-- Will be striped -->
<nomadx-table striped="true"></nomadx-table> <!-- Will be striped -->
<nomadx-table striped="false"></nomadx-table> <!-- Will NOT be striped -->
Sortable
Nomadx tables make it easy to enable per-column sorting through the sortable
attribute. By default, no columns will be sortable, but including the attribute or setting it to "true"
will enable sorting for all columns. You may also specify a list of columns indexes for which sorting should be enabled.
Please note that the first column has an index of 1
<nomadx-table sortable></nomadx-table> <!-- All columns will be sortable -->
<nomadx-table sortable="true"></nomadx-table> <!-- All columns will be sortable -->
<nomadx-table sortable="false"></nomadx-table> <!-- No columns will be sortable -->
<nomadx-table sortable="1 2 3"></nomadx-table> <!-- Columns 1, 2, and 3 will be sortable -->
<nomadx-table sortable="1 3 5"></nomadx-table> <!-- Columns 1, 3, and 5 will be sortable -->
Fixed Width
Nomadx tables are responsive by default, but if you'd like to make any column fixed-width, it is simple to do so with the fixed-width
attribute. This operates in a similar way to sortable
(above).
Please note that the first column has an index of 1
<nomadx-table fixed-width></nomadx-table> <!-- All columns will be fixed-width -->
<nomadx-table fixed-width="true"></nomadx-table> <!-- All columns will be fixed-width -->
<nomadx-table fixed-width="false"></nomadx-table> <!-- No columns will be fixed-width -->
<nomadx-table fixed-width="1 2 3"></nomadx-table> <!-- Columns 1, 2, and 3 will be fixed-width -->
<nomadx-table fixed-width="1 3 5"></nomadx-table> <!-- Columns 1, 3, and 5 will be fixed-width -->
In order to specify the width of the column, simple use CSS to set a --fixed-width
variable on the column, either via :nth-child
or via column-[name]
.
nomadx-table .column:nth-of-type(1) {
--fixed-width: 128px;
}
/*
* Class Selector is "column-" followed by the column header's content formatted to kebab case
* In this example, the column header is "My Awesome Column"
*/
nomadx-table .column-my-awesome-column {
--fixed-width: 128px;
}
Styling
<nomadx-table>
offers a number of CSS variables to modify the default styling of the table.
Variable | Default Value |
---|---|
--row-background-color | #fff; |
--stripe-background-color | #fafafa; |
--focused-row-background-color | #e1f5fe; |
--focused-stripe-background-color | #e1f5fe; |
--table-border | 1px solid #dfe2e5; |
--cell-padding | 12px; |
--sort-active-color | #000; |