https://github.com/aarongustafson/table-modifiable
A web component that enables users to hide & show columns on an HTML table.
https://github.com/aarongustafson/table-modifiable
light-dom table web-components
Last synced: 5 months ago
JSON representation
A web component that enables users to hide & show columns on an HTML table.
- Host: GitHub
- URL: https://github.com/aarongustafson/table-modifiable
- Owner: aarongustafson
- License: mit
- Created: 2025-12-09T23:21:10.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-12-15T04:43:33.000Z (6 months ago)
- Last Synced: 2025-12-17T23:59:58.092Z (6 months ago)
- Topics: light-dom, table, web-components
- Language: JavaScript
- Homepage: https://aarongustafson.github.io/table-modifiable/
- Size: 107 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# table-modifiable Web Component
[](https://www.npmjs.com/package/@aarongustafson/table-modifiable) [](https://github.com/aarongustafson/table-modifiable/actions)
A web component that enables users to hide & show columns on an HTML table.
## Demo
[Live Demo](https://aarongustafson.github.io/table-modifiable/demo/) ([Source](./demo/index.html))
Additional demos:
- [ESM CDN Demo](https://aarongustafson.github.io/table-modifiable/demo/esm.html) ([Source](./demo/esm.html))
- [Unpkg CDN Demo](https://aarongustafson.github.io/table-modifiable/demo/unpkg.html) ([Source](./demo/unpkg.html))
## Installation
```bash
npm install @aarongustafson/table-modifiable
```
## Usage
### Option 1: Auto-define the custom element (easiest)
Import the package to automatically define the `` custom element:
```javascript
import '@aarongustafson/table-modifiable';
```
Or use the define-only script in HTML:
```html
```
### Option 2: Import the class and define manually
Import the class and define the custom element with your preferred tag name:
```javascript
import { TableModifiableElement } from '@aarongustafson/table-modifiable/table-modifiable.js';
customElements.define('my-custom-name', TableModifiableElement);
```
You can also call the provided helper to register the element without importing the class:
```javascript
import { defineTableModifiable } from '@aarongustafson/table-modifiable/define.js';
defineTableModifiable('my-custom-name');
```
### Basic Example
```html
Name
Email
Phone
John Doe
john@example.com
555-1234
```
## Attributes
| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `removable` | `string` | `""` | Comma-separated list of all column names that can be shown/hidden |
| `start-with` | `string` | (all removable) | Comma-separated list of which columns should be visible by default. If not specified, all removable columns will be shown initially |
| `button-label` | `string` | `"Modify Table"` | Text label for the toggle button |
| `button-aria-label` | `string` | (same as button-label) | Accessible label for the toggle button. Use this to provide a more descriptive label for screen readers if needed |
| `tools-label` | `string` | `"Show/Hide Columns"` | Heading text for the popover panel |
## Properties
All of the attributes above have matching camelCase properties (`removable`, `startWith`, `buttonLabel`, `buttonAriaLabel`, `toolsLabel`). Setting a property updates the corresponding attribute and schedules the component to re-render.
```javascript
const modifiable = document.querySelector('table-modifiable');
modifiable.removable = 'Name,Email';
modifiable.startWith = 'Name';
```
## Events
The component fires custom events that you can listen to:
| Event | Description | Detail |
|-------|-------------|--------|
| `table-modifiable:change` | Fired when a column's visibility is toggled | `{ column: string, visible: boolean }` |
### Example Event Handling
```javascript
const element = document.querySelector('table-modifiable');
element.addEventListener('table-modifiable:change', (event) => {
console.log(`Column "${event.detail.column}" is now ${event.detail.visible ? 'visible' : 'hidden'}`);
});
```
## CSS Custom Properties
| Property | Default | Description |
|----------|---------|-------------|
| `--table-modifiable-tool-bg` | (none) | Background color for the modification tools popover |
| `--table-modifiable-tool-color` | (none) | Text color for the modification tools popover |
### Example Styling
You can style the generated elements directly to customize the appearance:
```css
/* Style the toggle button */
.modification-tools-toggle {
background: #0969da;
color: white;
border: none;
padding: 0.5rem 1rem;
border-radius: 4px;
font-size: 1rem;
cursor: pointer;
}
.modification-tools-toggle:hover {
background: #0860ca;
}
/* Style the popover */
.modification-tools {
background: var(--table-modifiable-tool-bg, white);
color: var(--table-modifiable-tool-color, #333);
padding: 1rem;
border-radius: 6px;
border: 1px solid #d0d7de;
box-shadow: 0 8px 24px rgba(140, 149, 159, 0.2);
min-width: 250px;
}
.modification-tools-heading {
font-weight: bold;
display: block;
margin-bottom: 0.75rem;
font-size: 1.1rem;
}
.modification-tools ul {
list-style: none;
padding: 0;
margin: 0;
display: flex;
flex-direction: column;
gap: 0.5rem;
}
.modification-tools li {
margin: 0;
}
.modification-tools label {
cursor: pointer;
user-select: none;
}
```
## How It Works
This component wraps an HTML table and adds interactive controls to show/hide columns:
1. **Place your table inside the component**: The component uses Light DOM, so your table remains in the regular DOM and is fully accessible.
2. **Specify removable columns**: Use the `removable` attribute to list which columns can be toggled. The column names must match the text content of the `` elements in the first header row exactly.
3. **Set initial visibility**: Optionally use `start-with` to specify which columns should be visible when the page loads. Any columns in `removable` but not in `start-with` will be hidden initially.
4. **Toggle via popover**: The component creates a button that opens a popover with checkboxes. Users can check/uncheck these to show/hide the corresponding columns. The popover uses the native [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API).
5. **Customize labels**: Use the `button-label`, `button-aria-label`, and `tools-label` attributes to customize the text shown to users.
**Note**: This component works with simple tables (one header row, matching body cells). It does not support `colspan` or `rowspan` attributes.
## Advanced Examples
### Table with Multiple Columns
```html
Product
Price
Stock
Category
Widget
$9.99
42
Tools
```
### Customizing Labels
```html
Name
Email
Phone
Address
Jane Doe
jane@example.com
555-5678
123 Main St
```
## TypeScript
This package ships bundled type definitions (`table-modifiable.d.ts`). You can import the element type, the change event payload, and the registration helper:
```ts
import type {
TableModifiableElement,
TableModifiableChangeEvent,
} from '@aarongustafson/table-modifiable/table-modifiable.js';
import { defineTableModifiable } from '@aarongustafson/table-modifiable/define.js';
defineTableModifiable();
const element = document.querySelector('table-modifiable') as TableModifiableElement;
element.addEventListener(
'table-modifiable:change',
(event: TableModifiableChangeEvent) => {
console.log(event.detail.column, event.detail.visible);
},
);
```
## Browser Support
This component uses modern web standards:
- Custom Elements v1
- ES Modules
- Popover API
For older browsers, you may need polyfills.
## Development
```bash
# Install dependencies
npm install
# Run tests
npm test
# Run tests with coverage
npm run test:coverage
# Lint code
npm run lint
# Format code
npm run format
# View demo
open demo/index.html
```
## License
MIT © [Aaron Gustafson](https://www.aaron-gustafson.com/)