@nomadx/table v0.3.3-alpha

@nomadx/table

<nomadx-table> is a set of vanilla web-components to simplify the creation of accessible, responsive HTML tables.

Try the demo!

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&Tab;Column B&Tab;Column C&Tab;Column D
    0&Tab;true&Tab;Hello&Tab;World!
    2&Tab;false&Tab;Foobar&Tab;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

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.