MatrixEditor
Edit a dynamic matrix with typed cells, row and column bulk operations, change tracking and correlated bulk saving.
Live TypeScript example
Try the component here, then use the source below in your application.
- JavaScript
- 5.0 KiB
- Component CSS
- 1.4 KiB
- Shared theme CSS
- 3.8 KiBonce per application
How sizes are measured
The JavaScript figure includes this component’s required helpers. CSS includes its styling dependencies. Each entry is bundled separately for ES2022, minified, then compressed with gzip level 9. Your bundler may share helpers across components. Images, fonts, examples and application code are excluded.
Before compression: JavaScript 13.2 KiB; component CSS 5.5 KiB. These figures describe browser assets, not the complete package download.
View all component measurements →Tab through typed cells. Space changes checkboxes. Row and column All/None commands provide bulk changes; disabled cells remain protected.
import '@blukavantui/web/theme.css'
import {createMatrixEditor} from '@blukavantui/web/matrix-editor';
import '@blukavantui/web/matrix-editor.css';
export function mount(host:HTMLElement) {
const status=document.createElement("p");status.setAttribute("role","status");
const component=createMatrixEditor(host, {
"Rows": [
{
"Key": "admin",
"Label": "Administrators",
"Description": "Manage the workspace"
},
{
"Key": "editor",
"Label": "Editors",
"Description": "Manage assigned content"
},
{
"Key": "viewer",
"Label": "Viewers",
"Description": "Read-only access"
},
{
"Key": "guest",
"Label": "Guests",
"Description": "Restricted access",
"IsDisabled": true
}
],
"Columns": [
{
"Key": "read",
"Label": "Read",
"ValueType": "Boolean"
},
{
"Key": "write",
"Label": "Write",
"ValueType": "Boolean"
},
{
"Key": "publish",
"Label": "Publish",
"ValueType": "Boolean"
},
{
"Key": "limit",
"Label": "Daily limit",
"ValueType": "Number",
"IsRequired": true
},
{
"Key": "scope",
"Label": "Access scope",
"ValueType": "Choice",
"IsRequired": true
}
],
"Cells": [
{
"RowKey": "admin",
"ColumnKey": "read",
"Value": "true",
"IsReadOnly": false
},
{
"RowKey": "admin",
"ColumnKey": "write",
"Value": "true",
"IsReadOnly": false
},
{
"RowKey": "admin",
"ColumnKey": "publish",
"Value": "true",
"IsReadOnly": false
},
{
"RowKey": "admin",
"ColumnKey": "limit",
"Value": "100",
"IsReadOnly": false
},
{
"RowKey": "admin",
"ColumnKey": "scope",
"Value": "all",
"IsReadOnly": false
},
{
"RowKey": "editor",
"ColumnKey": "read",
"Value": "true",
"IsReadOnly": false
},
{
"RowKey": "editor",
"ColumnKey": "write",
"Value": "false",
"IsReadOnly": false
},
{
"RowKey": "editor",
"ColumnKey": "publish",
"Value": "false",
"IsReadOnly": false
},
{
"RowKey": "editor",
"ColumnKey": "limit",
"Value": "50",
"IsReadOnly": false
},
{
"RowKey": "editor",
"ColumnKey": "scope",
"Value": "team",
"IsReadOnly": false
},
{
"RowKey": "viewer",
"ColumnKey": "read",
"Value": "true",
"IsReadOnly": false
},
{
"RowKey": "viewer",
"ColumnKey": "write",
"Value": "false",
"IsReadOnly": false
},
{
"RowKey": "viewer",
"ColumnKey": "publish",
"Value": "false",
"IsReadOnly": true
},
{
"RowKey": "viewer",
"ColumnKey": "limit",
"Value": "10",
"IsReadOnly": false
},
{
"RowKey": "viewer",
"ColumnKey": "scope",
"Value": "own",
"IsReadOnly": false
},
{
"RowKey": "guest",
"ColumnKey": "read",
"Value": "true",
"IsReadOnly": false
},
{
"RowKey": "guest",
"ColumnKey": "write",
"Value": "false",
"IsReadOnly": false
},
{
"RowKey": "guest",
"ColumnKey": "publish",
"Value": "false",
"IsReadOnly": false
},
{
"RowKey": "guest",
"ColumnKey": "limit",
"Value": "1",
"IsReadOnly": false
},
{
"RowKey": "guest",
"ColumnKey": "scope",
"Value": "own",
"IsReadOnly": false
}
],
"Options": [
{
"ColumnKey": "scope",
"Key": "own",
"Label": "Own records"
},
{
"ColumnKey": "scope",
"Key": "team",
"Label": "Team records"
},
{
"ColumnKey": "scope",
"Key": "all",
"Label": "All records"
}
],
"IsReadOnly": false,
"ShowBulkActions": true
}, { SaveRequested: (requestId, changes, cells) => {
// Replace browser storage with your API; acknowledge only after it succeeds.
try {
localStorage.setItem('bluui-starter:matrix-editor', JSON.stringify(cells));
queueMicrotask(() => component.update({SaveResultRequestId:requestId, SaveResultSuccess:true, SaveResultMessage:'Saved in this browser.'}));
} catch {
queueMicrotask(() => component.update({SaveResultRequestId:requestId, SaveResultSuccess:false, SaveResultMessage:'Save failed. Your edits are retained.'}));
}
} });
host.append(status);
return {destroy(){component.destroy();status.remove();}};
}
const instance = mount(document.getElementById('example')!)
// When this page or framework component is removed:
// instance.destroy()
Install the library and add the host element
npm install https://blukavantui.blutekmedia.com/downloads/blukavantui-web-0.6.2.tgz<div id="example"></div>This example uses the downloadable @blukavantui/web package. Your application handles persistence and authentication through its typed callbacks. The starter ZIP includes this same example.
createMatrixEditor
Pass options as the second argument and callbacks in the third argument. Keep the returned instance to update options or dispose it when its view is removed.
import { createMatrixEditor } from '@blukavantui/web/matrix-editor';
import '@blukavantui/web/matrix-editor.css';Load @blukavantui/web/theme.css once in your app shell.createMatrixEditor(host: HTMLElement, options: T.MatrixEditorOptions, events?: T.MatrixEditorEvents)Reference for @blukavantui/web 0.6.2. Required and optional follow the shipped TypeScript declarations; optional does not imply a particular default. Pass typed arrays and objects directly where shown.
Options
12| Name | Type / requirement | Usage |
|---|---|---|
Rows | BluMatrixRow[]Required | Ordered matrix row definitions. |
Columns | BluMatrixColumn[]Required | Ordered typed column definitions. |
Cells | BluMatrixCell[]Required | Sparse cell values; missing Boolean cells begin false and other missing cells begin empty. |
Options | BluMatrixOption[]Required | Choices for columns whose ValueType is Choice; may be empty. |
IsReadOnly | booleanOptional | Disables all editing and bulk operations. Default: False. |
ShowBulkActions | booleanOptional | Allows setting all editable Boolean values in a row or column. Default: True. |
SaveResultRequestId | stringOptional | Echo the latest OnSaveRequested.RequestId after persistence finishes. Default: "". |
SaveResultSuccess | booleanOptional | True accepts the submitted snapshot; False retains editable changes. Default: False. |
SaveResultMessage | stringOptional | Success or failure feedback for the matching request. Default: "". |
ResetKey | stringOptional | Change this value to reload the supplied data and discard local history when not saving. Default: "". |
AccessibleLabel | stringOptional | Accessible component name; empty uses the component default. Default: "". |
ExtendedClass | stringOptional | Additional CSS classes on the Block root. Default: "". |
Callbacks
3| Name | Type / requirement | Usage |
|---|---|---|
CellsChanged | (cells: T.BluMatrixCell[], changes: T.BluMatrixCell[]) => void | Promise<void>Optional | |
SaveRequested | (requestId: string, changes: T.BluMatrixCell[], cells: T.BluMatrixCell[]) => void | Promise<void>Optional | |
Error | (message: string) => void | Promise<void>Optional |
Instance methods & properties
3| Name | Signature / type | Usage |
|---|---|---|
element | HTMLElement | Root owned by this instance. Dispose before removing its host. |
update | (patch: Partial<T.MatrixEditorOptions>) => void | Apply a partial options update to this instance. |
destroy | () => void | Dispose the instance and its listeners when the view is removed. |
Related data types
Expand a type for its fields and allowed values.
BluMatrixCell
interface BluMatrixCell {
/** Stable row key. */
RowKey: string;
/** Stable column key. */
ColumnKey: string;
/** Text representation of the cell value; Boolean values use true or false. */
Value: string;
/** Prevents editing this individual cell. */
IsReadOnly?: boolean;
}BluMatrixColumn
interface BluMatrixColumn {
/** Unique stable column key. */
Key: string;
/** Visible column heading. */
Label: string;
/** Boolean, Text, Number or Choice. */
ValueType?: "Boolean" | "Text" | "Number" | "Choice";
/** Requires a nonempty value; Boolean false is valid. */
IsRequired?: boolean;
/** Prevents editing this column. */
IsReadOnly?: boolean;
}BluMatrixOption
interface BluMatrixOption {
/** Choice column receiving this option. */
ColumnKey: string;
/** Stored choice value. */
Key: string;
/** Visible choice label. */
Label: string;
}BluMatrixRow
interface BluMatrixRow {
/** Unique stable row key. */
Key: string;
/** Visible row heading. */
Label: string;
/** Optional row help text. */
Description?: string;
/** Prevents edits and bulk changes to this row. */
IsDisabled?: boolean;
}Use these inputs, events, actions and structures in Service Studio. Names and data bindings are specific to the native Blocks.
Part of the full commercial BluKavantUI for OutSystems edition. View OutSystems editions →
Open OutSystems showcase ↗- Web runtime
- Partially supported
- TypeScript
- Partially supported
- OutSystems
- Partially supported
Statuses describe the component’s rendered code and interactions. Supply accessible content and follow the component guidance when integrating it.
Accessibility guidance →Purpose and use
Edit a dynamic matrix with typed cells, row and column bulk operations, change tracking and correlated bulk saving.
Keyboard design guidance
Tab through typed cells. Space changes checkboxes. Row and column All/None commands provide bulk changes; disabled cells remain protected.
See the support status above for review coverage and any limitations.
In your application
Provide useful labels, preserve visible focus, and test the component with your actual content. Use text alongside status colors and check contrast in each state.
Events0No events yet.
Interact with an example to see its events.