Grid

Explore filtering, selection, bulk edits, row actions, and expandable details.

IMPLEMENTATION GUIDE

Connect Grid to your data and saved preferences

Build the consumer in layers: server pages, saved views, personal column layouts, and recovery. The Grid manages interaction; your application owns database access and persistence.

Web / TypeScript

Connect server pagination

Works with Web Pro 1.0.1. Use Mode = Infinite even when the UI uses numbered pages. PageSize controls the visible page; CacheBlockSize controls the server fetch. At 25 visible rows and 100-row blocks, pages 1–4 can share the first request. Page 5 asks for rows 100–199. Do not calculate a second page number in your callback.

Complete mounting, loading, retry and cleanup adapter

import { createGrid } from '@blukavantui/pro/grid'
import type { GridDataRequest, GridInstance } from '@blukavantui/pro/grid'
import '@blukavantui/community/theme.css'
import '@blukavantui/pro/grid.css'

type Customer = { Id: string; Name: string; Revenue: number }
type Page = { Rows: Customer[]; TotalRowCount: number }

// /api/customers/page is a route YOU implement. See the server recipe.
export function mountCustomers(host: HTMLElement, csrfToken: string) {
  let disposed = false
  let grid: GridInstance<Customer>
  const pending = new Set<AbortController>()

  async function load(request: GridDataRequest) {
    // Yield once: the initial event can occur while createGrid is running.
    await Promise.resolve()
    if (disposed) return
    const controller = new AbortController()
    pending.add(controller)
    try {
      const response = await fetch('/api/customers/page', {
        method: 'POST', credentials: 'same-origin', signal: controller.signal,
        headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': csrfToken },
        body: JSON.stringify(request),
      })
      if (!response.ok) throw new Error('Page request failed')
      const page: Page = await response.json()
      if (!Array.isArray(page.Rows) || !Number.isSafeInteger(page.TotalRowCount)
          || page.TotalRowCount < 0 || page.Rows.length > request.EndRow - request.StartRow) {
        throw new Error('Invalid page response')
      }
      if (!disposed) {
        // Pass the original ID. False means the request is no longer current.
        grid.completeDataRequest(request.RequestId, page.Rows, page.TotalRowCount)
      }
    } catch {
      if (!disposed) grid.failDataRequest(request.RequestId, 'Could not load this page. Retry loading.')
    } finally { pending.delete(controller) }
  }

  grid = createGrid<Customer>(host, {
    Columns: [
      { Field: 'Name', Header: 'Customer', IsSortable: true, IsFilterable: true },
      { Field: 'Revenue', Type: 'Currency', IsSortable: true, IsFilterable: true },
    ],
    RowKeyField: 'Id', Mode: 'Infinite',
    Config: { EnablePagination: true, PageSize: 25, CacheBlockSize: 100,
      MaxBlocksInCache: 5, DataRequestTimeout: 30 },
    Events: { OnDataRequested: load },
  })
  return {
    grid,
    retry: () => grid.retryLoading(),
    destroy() { disposed = true; pending.forEach(c => c.abort()); grid.destroy() },
  }
}

Download this example

Value	Meaning	Example
StartRow	Zero-based, inclusive offset.	0
EndRow	Exclusive end; requested count = EndRow − StartRow.	100
Sort / native SortJson	Ordered field/direction pairs. Allowlist fields; append a stable Id tie-breaker.	[{"Field":"Name","Direction":"asc"}]
Filter / native FilterJson	Column filter model. Decode each allowed field, type, operator and value.	{} means no column filters
SearchText	Global search applied to the entire authorized source.	acme
TotalRowCount	Count AFTER the same permissions, filters and search; BEFORE paging.	243, not 100
Rows / native RowsJson	Only the requested slice, with stable record IDs and original JSON value types.	100 objects, or fewer on the last block

Build the page endpoint

Create an application Server Action or API route named LoadCustomerPage. Its inputs are StartRow, EndRow, SortJson, FilterJson and SearchText. Return RowsJson (Text) and TotalRowCount (Integer). On Web, use the equivalent Rows array and JSON body. These names are your application code, not shipped actions.

Resolve the signed-in user and tenant on the server. Reject invalid offsets and requests larger than your agreed block limit (100 in this recipe). Do not silently truncate a larger block; the Grid would interpret the result incorrectly.
Parse sorting and filters into typed, allowlisted fields. Map Name and Revenue to fixed database expressions; allow only supported operators. Reject unsupported filters with a readable error. Never concatenate a browser field name or value into SQL.
Build one authorized query, apply global search and every column filter, then count it. Apply a deterministic sort, with Id as a final tie-breaker, and take EndRow − StartRow records starting at StartRow. Use matching predicates for count and rows; use a consistent database snapshot when exact count/page consistency matters.
Return an empty array with count 0 for no matches. Return the real count even when a deleted record makes the requested final page empty. Fetch rows from the database for every requested block; paging an already loaded partial list does not implement server pagination.

authorized = Customers WHERE TenantId = authenticatedTenant
matching   = authorized AND decodedColumnFilters AND globalSearch
TotalRowCount = COUNT(matching)
Rows = matching ORDER BY allowlistedSort, Id
                OFFSET StartRow LIMIT (EndRow - StartRow)
return { Rows, TotalRowCount }

In OutSystems, an Aggregate can supply simple static filters and paging. For dynamic filters use Advanced SQL with bound values (Expand Inline = False). Dynamic ordering must be constructed exclusively from fixed server mappings. Index tenant/access predicates and the common sort/search fields. The Grid renders pages; it does not reduce the cost of an unindexed database query.

The example POSTs to /api/customers/page. Return HTTP 200 with { "Rows": [...], "TotalRowCount": 243 }. Non-2xx responses call failDataRequest. Keep RequestId in the client closure and pass it unchanged to completeDataRequest; a late response may be rejected after sorting or filtering changes. Do not replace the Grid’s entire dataset with setData for each Infinite-mode response.

Save column preferences with the released Web API

The current downloadable Pro 1.0.1 wrapper supports Columns, update and setColumnVisible. It does not expose getView, applyView, getColumnLayout, OnViewSaveRequested or the named-view workbench. Those newer methods shown in the website runtime must not be assumed available in that download.

For this release, keep visibility and width in your own settings controls. Load them before mounting, change the Columns configuration, then save your own versioned preferences through an authenticated endpoint. This adapter intentionally tracks your controls; it cannot observe arbitrary header resizing or reordering through a callback that the release does not expose.

Released Web column preference adapter

import { createGrid } from '@blukavantui/pro/grid'
import type { GridColumn } from '@blukavantui/pro/grid'

type Customer = { Id: string; Name: string; Revenue: number }
type Preferences = { Version: 1; RevenueVisible: boolean; RevenueWidth: number }

// A small application-owned preference UI for the released Web Pro 0.2.4 API.
// Load saved preferences BEFORE calling this function. Style imports as in paging.
export function mountPreferences(host: HTMLElement, rows: Customer[], saved: Preferences,
  persist: (value: Preferences) => Promise<void>) {
  let preferences = { ...saved }
  function columns(): GridColumn<Customer>[] {
    return [
      { Field: 'Name', Header: 'Customer' },
      { Field: 'Revenue', Type: 'Currency', IsHidden: !preferences.RevenueVisible,
        Width: preferences.RevenueWidth, Flex: 0 },
    ]
  }
  const grid = createGrid(host, { Columns: columns(), Rows: rows, RowKeyField: 'Id' })
  return {
    // Wire your own visibility toggle and width input to this method.
    change(revenueVisible: boolean, revenueWidth: number) {
      if (!Number.isFinite(revenueWidth)) return
      preferences = { Version: 1, RevenueVisible: revenueVisible,
        RevenueWidth: Math.min(600, Math.max(100, revenueWidth)) }
      grid.update({ Columns: columns() })
    },
    // Await this in your Save preferences button handler; show failure/retry there.
    save: () => persist({ ...preferences }),
    destroy: () => grid.destroy(),
  }
}

Download this example

Design saved-view storage

Create these application entities. Use a stable GridKey such as customers-v1, not a DOM ID. ViewJson contains a definition of the view, not customer rows.

Entity	Suggested fields	Uniqueness / access
GridSavedView	Id, TenantId, OwnerUserId, GridKey, Key, Name, Scope, ViewJson, SchemaVersion, Revision, UpdatedAt	Unique (TenantId, GridKey, Key); Personal requires owner; Team requires team-read or team-edit permission.
GridColumnPreference	TenantId, UserId, GridKey, LayoutJson, SchemaVersion, Revision	Unique (TenantId, UserId, GridKey); only that user may update.

Validate the view version, permitted fields, filter sizes, sort directions and limits on the server. Derive ownership from the session; never trust Scope or an owner ID sent by the browser. Use Revision for optimistic concurrency so two tabs cannot silently overwrite each other. Keep your application SchemaVersion separate from the component’s Version field. A hidden column is a preference, not an authorization rule.

The full named-view workflow below is available in the published OutSystems producer. For Web 1.0.1, store only the settings your own application owns, and label that UI “Column preferences.” Full workbench capture/restore needs a Web release exposing the matching methods; changing documentation or using a TypeScript cast cannot add runtime support.

Check paging and persistence end to end

Seed 243 test rows: first block 100, final block 43, filtered total 243. With 25-row pages the last page shows 18 records.
Search down to 7 matches: return count 7 and show one page. Clear search and recover the full count.
Delay one response, change sort/filter and verify the old request does not replace the new query. Check failed loading and retry.
Save preferences, reload, and verify restoration only for the same user and grid. Reject another user’s preference ID.
Infinite-mode CSV export covers cached rows. Implement a separate authorized server export for the full matching dataset.

OutSystems / Service Studio

Place the native Grid and bind state

In Manage Dependencies select BluGrid, BluGridColumn, BluGridConfig and the actions used below from BluKavantUi_Pro_Grid. Use the published producer with ViewsJson and OnViewSaveRequested for named views; refresh references and publish your consumer. Install the Community theme and configure your Pro license first.

CustomersScreen
└─ Your existing Layout → Content slot
   └─ GridRegion (new Container)
      └─ If PreferencesLoaded
         └─ CustomersGrid (referenced BluGrid Block)

Create Columns (BluGridColumn List), GridConfig (BluGridConfig), SavedViewsJson (Text, "[]"), SavedLayoutJson (Text, empty) and PreferencesLoaded (Boolean, False). Use a Data Action to load preferences/views, then set PreferencesLoaded = True. This ensures initial preferences exist before the Block mounts; do not toggle the If for routine page requests.

Block input / config	Bind / assign
Columns	Columns; define Name (Text) and Revenue (Currency) with sortable/filterable enabled.
RowKeyField	"Id"; every returned row has a unique stable Id.
Mode / RowsJson	"Infinite" / "[]"
Config	GridConfig
GridConfig.EnablePagination / PageSize	True / 25
GridConfig.CacheBlockSize / MaxBlocksInCache	100 / 5
GridConfig.DataRequestTimeout	30 (seconds)
GridConfig.ShowWorkbench	True (published producer)
InitialColumnLayoutJson	SavedLayoutJson
ViewsJson	SavedViewsJson
ViewStorageKey	"" for database-owned views; see browser-only option below.

Keep one initialized Grid inside GridRegion. Public Client Actions below receive GridRegion.Id, not CustomersGrid.Id and not a hard-coded HTML identifier.

Wire every page request argument

Create a screen Client Action HandleDataRequested and select it on CustomersGrid.OnDataRequested. Add these handler inputs and explicitly map them:

Handler input	Type	Event mapping
RequestedRequestId	Text	RequestedRequestId = RequestId
RequestedStartRow	Integer	RequestedStartRow = StartRow
RequestedEndRow	Integer	RequestedEndRow = EndRow
RequestedSortJson	Text	RequestedSortJson = SortJson
RequestedFilterJson	Text	RequestedFilterJson = FilterJson
RequestedSearchText	Text	RequestedSearchText = SearchText

Value	Meaning	Example
StartRow	Zero-based, inclusive offset.	0
EndRow	Exclusive end; requested count = EndRow − StartRow.	100
Sort / native SortJson	Ordered field/direction pairs. Allowlist fields; append a stable Id tie-breaker.	[{"Field":"Name","Direction":"asc"}]
Filter / native FilterJson	Column filter model. Decode each allowed field, type, operator and value.	{} means no column filters
SearchText	Global search applied to the entire authorized source.	acme
TotalRowCount	Count AFTER the same permissions, filters and search; BEFORE paging.	243, not 100
Rows / native RowsJson	Only the requested slice, with stable record IDs and original JSON value types.	100 objects, or fewer on the last block

Start
→ LoadCustomerPage (your Server Action)
    StartRow  = RequestedStartRow
    EndRow    = RequestedEndRow
    SortJson  = RequestedSortJson
    FilterJson = RequestedFilterJson
    SearchText = RequestedSearchText
→ BluGrid_CompleteDataRequest (public Client Action)
    RegionId = GridRegion.Id
    RequestId = RequestedRequestId
    RowsJson = LoadCustomerPage.RowsJson
    TotalRowCount = LoadCustomerPage.TotalRowCount
    SummaryJson = ""
→ Check ErrorMessage; End

All Exceptions handler
→ BluGrid_FailDataRequest
    RegionId = GridRegion.Id
    RequestId = RequestedRequestId
    Message = "Could not load customers. Please retry."
→ End

Keep the requested ID in that handler’s input, not a shared screen variable that the next request overwrites. Accepted = False can mean a stale request; ignore it unless ErrorMessage reports an actual failure. Wire OnDataError.Code and Message to your feedback/logging action. A Retry button can call BluGrid_ReloadData with GridRegion.Id. Leave SummaryJson empty unless you implement the documented server-summary contract.

Query and count the authorized database rows

Resolve the signed-in user and tenant on the server. Reject invalid offsets and requests larger than your agreed block limit (100 in this recipe). Do not silently truncate a larger block; the Grid would interpret the result incorrectly.
Parse sorting and filters into typed, allowlisted fields. Map Name and Revenue to fixed database expressions; allow only supported operators. Reject unsupported filters with a readable error. Never concatenate a browser field name or value into SQL.
Build one authorized query, apply global search and every column filter, then count it. Apply a deterministic sort, with Id as a final tie-breaker, and take EndRow − StartRow records starting at StartRow. Use matching predicates for count and rows; use a consistent database snapshot when exact count/page consistency matters.
Return an empty array with count 0 for no matches. Return the real count even when a deleted record makes the requested final page empty. Fetch rows from the database for every requested block; paging an already loaded partial list does not implement server pagination.

authorized = Customers WHERE TenantId = authenticatedTenant
matching   = authorized AND decodedColumnFilters AND globalSearch
TotalRowCount = COUNT(matching)
Rows = matching ORDER BY allowlistedSort, Id
                OFFSET StartRow LIMIT (EndRow - StartRow)
return { Rows, TotalRowCount }

Create database storage for views and columns

Create these application entities. Use a stable GridKey such as customers-v1, not a DOM ID. ViewJson contains a definition of the view, not customer rows.

Entity	Suggested fields	Uniqueness / access
GridSavedView	Id, TenantId, OwnerUserId, GridKey, Key, Name, Scope, ViewJson, SchemaVersion, Revision, UpdatedAt	Unique (TenantId, GridKey, Key); Personal requires owner; Team requires team-read or team-edit permission.
GridColumnPreference	TenantId, UserId, GridKey, LayoutJson, SchemaVersion, Revision	Unique (TenantId, UserId, GridKey); only that user may update.

Save and restore named views

Changing columns, filters or grouping changes the current view. It does not save it. The workbench’s Save view command emits OnViewSaveRequested. Create HandleViewSaveRequested with these Text inputs:

Handler input	Explicit event mapping
RequestedRequestId	RequestedRequestId = RequestId
RequestedKey	RequestedKey = Key
RequestedName	RequestedName = Name
RequestedScope	RequestedScope = Scope
RequestedViewJson	RequestedViewJson = ViewJson

Call your own SaveGridView Server Action with the mapped values and the fixed GridKey. Validate Personal/Team permission and revision. Use RequestedRequestId as the write-retry identifier; reject reuse with different content.
Commit the saved definition, then return the canonical authorized list as JSON. Assign SavedViewsJson = SaveGridView.ViewsJson; its binding updates the workbench. Show “View saved” only after this succeeds. This event has no CompleteViewSave action: use your own feedback on failure and leave the existing list untouched.
On a new visit, load that list before rendering. Each item has Key, Name, Scope and ViewJson, with ViewJson encoded as a JSON string, not a nested object. Serialize a typed list rather than manually escaping JSON.
The user can explicitly choose a named view in the workbench. For your own view picker, retrieve that authorized view and call BluGrid_ApplyView(RegionId = GridRegion.Id, ViewJson = SelectedView.ViewJson) after the Block is ready; inspect ErrorMessage.

For a separate Save current view button, call BluGrid_GetView(RegionId = GridRegion.Id), check ErrorMessage, and persist its ViewJson through your same Server Action. OnViewChanged reports draft view changes; use it for unsaved feedback, not as a second save command.

Persist column layout without overwriting a saved view

For automatic personal column preferences, wire OnColumnLayoutChanged.LayoutJson to HandleColumnLayoutChanged.RequestedLayoutJson (Text). Keep that value in a screen local. Save it on an explicit “Save column preferences” action, or debounce writes through one application-owned queue. Serialize or revision-check concurrent writes so a slow old resize cannot overwrite the latest layout.

Operation	Native flow
Capture on demand	BluGrid_GetColumnLayout(GridRegion.Id) → check ErrorMessage → store LayoutJson.
Restore on first mount	Load GridColumnPreference → SavedLayoutJson → InitialColumnLayoutJson.
Restore after mounting	BluGrid_ApplyColumnLayout(RegionId = GridRegion.Id, LayoutJson = saved JSON) → check ErrorMessage and AppliedLayoutJson.
Reset preferences	Remove only this user/grid preference, then remount with empty InitialColumnLayoutJson to use your configured column defaults. Resolve unsaved row edits first.

Layout JSON stores Version = 1 and a Columns array (Field, Width, Flex, IsHidden, Pinned). Preserve the complete component-produced value. Named views already include a layout: apply a chosen named view after the personal initial layout, so its columns win. Do not apply the personal layout again on every render. Applying a view can emit layout changes; suppress autosaving during deliberate restore if you want named views to leave the personal default alone.

Browser-only Save view and Restore view

ViewStorageKey enables the legacy browser storage controls. Choose a stable user- and grid-specific key, for example app + tenant + user + customers + schema version. This is convenient for personal use on one browser, but does not synchronize devices or provide team access. Leave it empty when your database owns named views to avoid two competing persistence systems. Browser storage is not a security boundary and may be cleared or unavailable.

Handle reports, edits and complete exports separately

Infinite mode only loads a small portion of the data. Grouping, pivot totals and full exports must operate on the entire authorized matching source. For published native server reports, set GridConfig.ReportMode = "Server" and ReportPageSize = 50. Wire OnReportRequested.RequestId and QueryJson into a dedicated report handler. Complete with BluGrid_CompleteReportRequest(RegionId, RequestId, ResultJson) or fail with BluGrid_FailReportRequest(RegionId, RequestId, Message).

Reference the public Server Action BluGrid_GetReportEngineSql for the shared grouping engine; the consumer still supplies its fixed entity/field mapping, authorization and bound filters. Never pass QueryJson directly as SQL. Report Scope = All may bypass user filters, but must preserve tenant/access predicates. A named view stores report settings, not cached report results; restoring it makes a new authorized request.

Before applying a view or reloading data, resolve pending edits with your Save/Discard flow. For saves, use OnSaveRequested.SaveToken and ChangesJson, persist with concurrency checks, then acknowledge that token with BluGrid_CompleteSave or BluGrid_FailSave. CSV export in Infinite mode covers cached rows; provide a server export action for all matching rows.

Verify the complete consumer

With 243 records, check the first and last page, then filter to 7 and to 0 records. Verify counts come from the database.
Change search while a request is slow; confirm its old response is ignored. Test retry after a database exception.
Save “My customers,” change columns without saving, and reload. Restore the saved view explicitly and confirm its columns/filter return.
Save personal column preferences and sign in on a second browser. Confirm database-backed preferences follow the account; browser-only storage does not.
Test another user and a user without Team-edit permission. Reject unauthorized reads/writes even when a view key is known.
Rename/remove a column in a test schema, migrate or invalidate the stored definition, and restore a safe default without breaking page load.

Related component: BluGridBasic

IMPLEMENTATION GUIDE

BluGridBasic: integration

Follow the setup steps, connect your application state, and verify each feature. Use the Code tab for the complete working Web example.

Web / TypeScript

Mount once, update state, clean up

Provide a real <div id="example"></div> in your view. Use the Code tab example's options and data as a starting point, then call this adapter with that host. Import the shared theme once per application and the component stylesheet with the component. Keep the returned instance for updates; call destroy() from your router/framework cleanup before removing the host.

Typed mounting and cleanup adapter

import { createGridBasic } from '@blukavantui/community/grid-basic'
import '@blukavantui/community/theme.css'
import '@blukavantui/community/grid-basic.css'

type Options = NonNullable<Parameters<typeof createGridBasic>[1]>
type Events = NonNullable<Parameters<typeof createGridBasic>[2]>

export function mount(host: HTMLElement, options: Options, events: Events = {}) {
  const instance = createGridBasic(host, options, events)
  return {
    instance,
    update: (patch: Partial<Options>) => instance.update(patch),
    destroy: () => instance.destroy(),
  }
}

This helper takes your real options and callbacks; it does not fetch records or invent a backend. The Code tab’s working example supplies a usable data shape. Use stable record keys when updates refer to existing items.

Connect the features you need

Display a free read-oriented grid

ColumnsRowsRowKeyFieldHeightPageSizeEnablePaginationEnableSelectionSelectionChanged

Use GridBasic for Community tables with display, sorting, pagination and optional selection. Provide stable row identities and typed columns. Store SelectionChanged outside the table when it drives other controls. The full editing, workbench and server-report workflows belong to Pro Grid.

Verify: Test selection, a partial last page, empty rows and a large value using the intended locale.

Before shipping

Use representative real data, including empty, loading and failed requests.
Test keyboard interaction, Light and Dark appearance, and a narrow screen with your longest labels.
Navigate away and back; confirm cleanup, expected state restoration and no duplicated callbacks.

OutSystems / Service Studio

Reference the native producer

In Manage Dependencies, select BluGridBasic from BluKavantUi_Community_Grid, together with the structures and public actions used by its API. Refresh existing references before publishing your consumer. Inherit the shared Community theme in your application's theme.

Place the Block in your screen

ExampleScreen — Screen (your application)
└─ ExistingLayout — referenced Layout Block instance (child of ExampleScreen)
   └─ Content — existing slot on ExistingLayout
      └─ ComponentRegion — Container (child of that slot)
         └─ MainComponent — BluKavantUi_Community_Grid.BluGridBasic Block instance (child of ComponentRegion)

Reuse your screen’s existing Layout and its content slot; do not add a second layout. If your Layout names that slot differently, use its actual content slot. ComponentRegion is a new Container; MainComponent is a referenced Block instance.

Create and bind screen state

Create local variables on ExampleScreen for the values your application changes. Use the exact native types below; lists are typed OutSystems Lists, while inputs ending in Json are Text containing the documented JSON. Bind each MainComponent.Input to its matching StateInput local. Constants can instead use the default directly. Fill required data from your Aggregate or Data Action before enabling interaction.

MainComponent input	Screen local / native type	Initial value	Purpose
Columns	StateColumns · BluGridBasicColumn List	Required: supply your value. Default: Empty list	Columns to render in their supplied order.
RowsJson	StateRowsJson · Text	"[]"	JSON array of flat records; keys must be unique.
RowKeyField	StateRowKeyField · Text	"Id"	Field containing a unique text or number key.
Height	StateHeight · Text	"480px"	Grid height as px, rem, vh, dvh or percent.
PageSize	StatePageSize · Integer	25	Rows per page from the already loaded list.
EnablePagination	StateEnablePagination · Boolean	True	Show local page navigation.
EnableSelection	StateEnableSelection · Boolean	True	Allow selecting one row by clicking it.

All native input defaults

Input	Type	Default	Required
Columns	BluGridBasicColumn List	Empty list	Yes
RowsJson	Text	"[]"	No
RowKeyField	Text	"Id"	No
Height	Text	"480px"	No
PageSize	Integer	25	No
EnablePagination	Boolean	True	No
EnableSelection	Boolean	True	No
Locale	Text	"en-US"	No
Currency	Text	"USD"	No
TimeZone	Text	"UTC"	No
AccessibleLabel	Text	"Data table"	No
ExtendedClass	Text	""	No

Create the event handlers and map every argument

For each event you use, create the named screen Client Action below. Add its listed input parameters with the exact types. Select that action on MainComponent's event property, then enter each mapping explicitly. Event arguments and screen locals are different scopes.

OnError → HandleError

Validation or initialization error.

Handler input	Native type	Event mapping
RequestedMessage	Text	RequestedMessage = Message

Flow: Start → display the mapped error argument in your feedback region → End.

OnReady → HandleReady

Opaque handle passed to GridBasic_ClearSelection.

Handler input	Native type	Event mapping
RequestedGridHandle	Text	RequestedGridHandle = GridHandle

Flow: Start → run your application action using the mapped event arguments → End.

OnRowClicked → HandleRowClicked

Clicked row as JSON.

Handler input	Native type	Event mapping
RequestedRowJson	Text	RequestedRowJson = RowJson

Flow: Start → run your application action using the mapped event arguments → End.

For a JSON argument, use JSON Deserialize with the matching Structure or List shown in this component’s API. Do not deserialize unrelated payloads into the same structure. Keep the raw JSON only when the documented storage contract requires it.

OnSelectionChanged → HandleSelectionChanged

Selected row as JSON; null when cleared.

Handler input	Native type	Event mapping
RequestedRowJson	Text	RequestedRowJson = RowJson

Flow: Start → validate the requested value; assign the corresponding screen state so the Block receives it back → End.

Call the public Client Actions when needed

Add the action to your consuming screen's Client Action flow after MainComponent is ready. For actions with RegionId, use ComponentRegion.Id; that Container must hold exactly one initialized component. Map request tokens from the corresponding event, and check the returned success/error values before changing application state.

GridBasic_ClearSelection

Clear the selected row using the GridHandle emitted by OnReady.

Action input	Native type	Value / purpose
GridHandle	Text	Supply the matching application value. Default: See API

Action output	Native type	How to handle it

Verify in your consumer

Publish the consumer, supply representative data, trigger each connected event and inspect the mapped arguments. Check a failed request, a retry and leaving/reopening the screen. The table describes the native contract; the Web recipes can contain capabilities with different native names or availability. Use these native names and the API tab as the authority for Service Studio.

TYPESCRIPT / BROWSER

TypeScript example

Use the source below in your application. Try the interactive component in Playground or Examples.

Component sizePro v1.0.1 · minified + gzip

JavaScript: 367.1 KiB
Component CSS: 10.0 KiB
Shared theme CSS: 5.5 KiBonce per application

Size details

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 1293.3 KiB; component CSS 54.5 KiB. These figures describe browser assets, not the complete package download.

View all component measurements →

import '@blukavantui/community/theme.css'

import { createGrid } from "@blukavantui/pro/grid";
import "@blukavantui/pro/grid.css";
interface Customer {
  Id: number;
  Name: string;
  Seats: number;
}
export function mount(host: HTMLElement) {
  const toolbar = document.createElement("div"),
    save = document.createElement("button"),
    output = document.createElement("p");
  output.setAttribute("role", "status");
  save.textContent = "Save changes";
  save.type = "button";
  toolbar.append(save, output);
  host.append(toolbar);
  const grid = createGrid<Customer>(host, {
    RowKeyField: "Id",
    Columns: [
      { Field: "Name", Header: "Customer", IsEditable: true, Flex: 1 },
      { Field: "Seats", Type: "Number", IsEditable: true },
    ],
    Rows: [
      { Id: 1, Name: "Atlas Labs", Seats: 12 },
      { Id: 2, Name: "Northstar", Seats: 24 },
    ],
    Config: {
      ShowWorkbench:true,ShowHistoryControls:true,ReportMode:"Client",
      Height: "360px",
      SelectionMode: "Multiple",
      EnablePagination: true,
      PageSize: 10,
    },
    Events: {
      OnViewSaveRequested:request=>{
        const views=grid.getNamedViews();const next={Key:request.Key||crypto.randomUUID(),Name:request.Name,Scope:request.Scope,ViewJson:request.ViewJson};
        grid.setNamedViews([...views.filter(view=>view.Key!==next.Key),next]);
        output.textContent='View saved for this page session, including columns and grouping/pivot.';
        // Persist the named views in your backend to restore them after a page reload.
      },
      OnEditStateChanged: (state) => {
        save.disabled = !state.HasChanges || state.IsSaving;
      },
    },
  });
  save.onclick = async () => {
    const request = await grid.beginSave();
    if (!request.SaveToken) return;
    try {
      // Replace this local persistence with a validated backend request returning canonical rows.
      localStorage.setItem("bluui-starter-grid", JSON.stringify(request.Rows));
      grid.completeSave(request.SaveToken, request.Rows);
      output.textContent = "Saved in this browser.";
    } catch {
      grid.failSave(request.SaveToken, [
        {
          RowId: "",
          Field: "",
          Code: "SAVE_FAILED",
          Message: "Could not save. Retry your changes.",
        },
      ]);
    }
  };
  return {
    destroy() {
      grid.destroy();
      toolbar.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-community-1.0.1.tgz
# Install your licensed Pro archive alongside Community
npm install ./blukavantui-pro-1.0.1.tgz

<div id="example"></div>

Download .ts source ↓TypeScript interfaces →Web API reference →Installation guide →

Download Community library ↓Community starter · 10 templates ↓Pro add-on & license →

Connect your application data

Community components use @blukavantui/community. The ten Pro components use the separate @blukavantui/pro add-on alongside Community. Your application handles persistence and authentication through its typed callbacks. Choose the matching edition when installing the example.

WEB · TYPESCRIPT

createGrid

Pass callbacks inside options.Events. ShowWorkbench provides the integrated Columns and Group / pivot popovers, saved views and reports. Column changes are temporary until you explicitly handle OnViewSaveRequested and persist its ViewJson. For saving records, await beginSave(), persist rows, then completeSave() or failSave(). Server grouping uses ReportMode with OnReportRequested; client reports operate only on loaded records.

v1.0.1

import { createGrid } from '@blukavantui/pro/grid';
import '@blukavantui/pro/grid.css';

Load @blukavantui/community/theme.css once in your app shell.

createGrid<R extends object>(host: HTMLElement, options: GridOptions<R>)

Reference for @blukavantui/pro 1.0.1. Required and optional follow the shipped TypeScript declarations; optional does not imply a particular default. Pass typed arrays and objects directly where shown.

Options

Name	Type / requirement	Usage
`Columns`	`GridColumn<R>[]`Required	Column definitions. Field names must belong to your row type R.
`Rows`	`R[]`Optional	Rows currently supplied by your application.
`RowKeyField`	`GridField<R>`Required	The field containing a stable, unique key for every row.
`Mode`	`"Client" \| "Infinite"`Optional	Client uses supplied rows. Infinite requests row ranges through OnDataRequested.
`Config`	`GridConfig`Optional	Grid layout, selection, editing, pagination and presentation settings.
`SearchText`	`string`Optional	Initial text search. Call setSearch() to change it after mounting.
`Views`	`GridNamedView[]`Optional
`View`	`GridView`Optional
`ColumnLayout`	`GridColumnLayout`Optional
`Events`	`GridEvents<R>`Optional	Grid callbacks belong in this options object, rather than a third factory argument.

Callbacks

Name	Type / requirement	Usage
`OnViewSaveRequested`	`(args_0: { GridId: string; RequestId: string; Key: string; Name: string; Scope: "Personal" \| "Team"; ViewJson: string; }) => void \| Promise<void>`Optional
`OnViewChanged`	`(args_0: { GridId: string; View: GridView; }) => void \| Promise<void>`Optional
`OnColumnLayoutChanged`	`(args_0: { GridId: string; Layout: GridColumnLayout; }) => void \| Promise<void>`Optional
`OnRowClick`	`(args_0: { GridId: string; Row: R; RowId: string; }) => void \| Promise<void>`Optional	Reports the clicked row and its key.
`OnRowDoubleClick`	`(args_0: { GridId: string; Row: R; RowId: string; }) => void \| Promise<void>`Optional	Reports a double-click on a row.
`OnSelectionChanged`	`(args_0: { GridId: string; Rows: R[]; }) => void \| Promise<void>`Optional	Reports the selected row objects.
`OnCellValueChanged`	`(args_0: { GridId: string; Row: R; RowId: string; Field: Extract<keyof R, string>; OldValue: unknown; NewValue: unknown; }) => void \| Promise<void>`Optional	Reports a changed cell, including old and new values.
`OnBatchValueChanged`	`(args_0: { GridId: string; Changes: { Row: R; RowId: string; Field: Extract<keyof R, string>; OldValue: unknown; NewValue: unknown; }[]; }) => void \| Promise<void>`Optional	One notification for all actual changes made by applyRowValues.
`OnEditStateChanged`	`(args_0: GridEditState & { GridId: string; }) => void \| Promise<void>`Optional	Reports changes to dirty, editing and saving state.
`OnDataError`	`(args_0: { GridId: string; Code: string; Message: string; }) => void \| Promise<void>`Optional	Reports a grid data error with a code and message.
`OnDataRequested`	`(args_0: GridDataRequest) => void \| Promise<void>`Optional	Requests a range of rows in Infinite mode. Complete or fail the matching RequestId.
`OnRowAction`	`(args_0: { GridId: string; ActionKey: string; RowId: string; Row: R; }) => void \| Promise<void>`Optional	Reports the action key and the row it applies to.
`OnBulkAction`	`(args_0: { GridId: string; ActionKey: string; RowIds: string[]; Rows: R[]; }) => void \| Promise<void>`Optional	Reports the action key and selected rows.
`OnRowExpansionChanged`	`(args_0: { GridId: string; RowId: string; IsExpanded: boolean; Row: R; }) => void \| Promise<void>`Optional	Reports whether a row detail view is expanded.

Instance methods & properties

Name	Signature / type	Usage
`element`	`HTMLElement`	The root DOM element owned by this instance.
`update`	`(patch: Partial<Pick<GridOptions<R>, "Columns" \| "Rows" \| "Config">>) => void`	Apply a partial options update to this instance.
`setSearch`	`(text: string) => void`	Apply a new text search.
`setData`	`(rows: R[]) => void`	Replace the supplied row data.
`getSelectedRows`	`() => R[]`	Return the selected row objects.
`clearSelection`	`() => void`	Clear the current row selection.
`selectPage`	`() => void`	Select rows on the current page.
`applyRowValues`	`(ids: (string \| number)[], values: Partial<R>, options?: { EmitCellEvents?: boolean; }) => GridEditState`	Stage values on the specified rows. Optional EmitCellEvents controls individual change notifications.
`applyCells`	`(cells: { RowId: string \| number; Field: Extract<keyof R, string>; Value: unknown; }[], options?: { EmitCellEvents?: boolean; }) => GridEditState`
`previewPaste`	`(text: string, rowId: string, field: Extract<keyof R, string>) => GridPastePreview`
`applyPaste`	`(token: string) => GridEditState`
`undo`	`() => GridEditState`
`redo`	`() => GridEditState`
`getFocusedCell`	`() => { RowId: string; Field: string; } \| null`
`getCellRange`	`() => { RowIds: string[]; Fields: string[]; } \| null`
`focusCell`	`(rowId: string, field: string) => void`
`getHistoryState`	`() => { CanUndo: boolean; CanRedo: boolean; }`
`getRows`	`(scope?: GridScope) => R[]`
`summarize`	`(options?: GridSummaryOptions) => GridSummary`
`exportXlsx`	`(options?: { FileName?: string; Scope?: GridScope; SheetName?: string; }) => void`
`getNamedViews`	`() => GridNamedView[]`
`setNamedViews`	`(views: GridNamedView[]) => void`
`requestSaveView`	`(name: string, scope?: "Personal" \| "Team", key?: string) => void`
`mountWorkbench`	`(host: HTMLElement) => () => void`
`getView`	`() => GridView`
`setReport`	`(report: GridReport \| null) => GridReport`	Null clears grouping and pivot and returns to Records.
`applyView`	`(view: GridView) => GridView`
`getColumnLayout`	`() => GridColumnLayout`
`applyColumnLayout`	`(layout: GridColumnLayout) => GridColumnLayout`
`resetFilters`	`() => void`
`fitColumns`	`() => void`
`autoSizeColumns`	`() => void`
`flushEdits`	`() => Promise<GridEditState>`	Commit the active editor and deliver pending edits without starting a save.
`beginSave`	`() => Promise<GridSaveRequest<R>>`	Begin a save and obtain the token and changed rows. Await your application’s persistence before acknowledging success.
`completeSave`	`(token: string, rows: R[]) => R[]`	Acknowledge a successful save with its matching token and canonical rows.
`failSave`	`(token: string, errors?: GridSaveError[]) => GridEditState`	Reject the matching save; pending edits are retained.
`cancelChanges`	`() => Promise<GridEditState>`	Discard pending changes.
`getEditState`	`() => GridEditState`	Read dirty, editing and saving state.
`completeDataRequest`	`(requestId: string, rows: R[], total: number, summary?: Record<string, number \| null>) => boolean`	Supply the rows and total count for a matching data request.
`failDataRequest`	`(requestId: string, message: string) => boolean`	Report a failure for a matching data request.
`retryLoading`	`() => void`	Retry a failed data load.
`setColumnVisible`	`(field: Extract<keyof R, string>, visible: boolean) => void`	Show or hide one column.
`setRowExpanded`	`(rowId: string, expanded: boolean) => void`	Open or close a row’s detail view.
`exportCsv`	`(options?: { FileName?: string; OnlySelected?: boolean; }) => void`	Export rows as CSV; optionally limit the export to selected rows.
`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.

GridAction

interface GridAction {
    Key: string;
    Label: string;
    Icon?: string;
    IsDisabled?: boolean;
    DisabledField?: string;
}

GridChange

interface GridChange {
    RowId: string;
    OriginalRowJson: string;
    RowJson: string;
    ChangedFieldsJson: string;
}

GridColumn

interface GridColumn<R extends object> {
    Field: GridField<R>;
    Header?: string;
    Type?: "Text" | "Number" | "Currency" | "Date" | "DateTime" | "Boolean";
    Width?: number;
    MinWidth?: number;
    Flex?: number;
    IsSortable?: boolean;
    IsFilterable?: boolean;
    IsResizable?: boolean;
    IsHidden?: boolean;
    IsPinned?: boolean;
    IsEditable?: boolean;
    IsRequired?: boolean;
    MaxLength?: number;
    DecimalPlaces?: number;
    HasMinValue?: boolean;
    MinValue?: number;
    HasMaxValue?: boolean;
    MaxValue?: number;
    SelectOptions?: {
        Value: string;
        Label: string;
    }[];
    StyleRules?: GridStyleRule[];
    Renderer?: "Badge" | "Progress" | "Action";
    ActionKey?: string;
    ActionLabel?: string;
    Color?: ComponentColor;
    ColorField?: GridField<R>;
}

GridColumnLayout

interface GridColumnLayout {
    Version: 1;
    Columns: {
        Field: string;
        Width: number;
        Flex: number;
        IsHidden: boolean;
        Pinned: 'None' | 'Left' | 'Right';
    }[];
}

GridConfig

interface GridConfig {
    Height?: string;
    RowHeight?: number;
    SelectionMode?: "None" | "Single" | "Multiple";
    IsLoading?: boolean;
    ExtendedClass?: string;
    Locale?: string;
    CurrencyCode?: string;
    TimeZone?: string;
    IsReadOnly?: boolean;
    ShowEditToolbar?: boolean;
    /** Integrated toolbar, cell-range selection, paste preview and grouped reports. Initialization-only. */
    ShowWorkbench?: boolean;
    /** Hide local undo/redo when a host owns shared history. */
    ShowHistoryControls?: boolean;
    EnablePagination?: boolean;
    PageSize?: number;
    CacheBlockSize?: number;
    MaxBlocksInCache?: number;
    DataRequestTimeout?: number;
    ShowFloatingFilters?: boolean;
    EnableRowDetails?: boolean;
    DetailHeight?: number;
    DetailTitleField?: string;
    RowActions?: GridAction[];
    BulkActions?: GridAction[];
    DetailFields?: {
        Field: string;
        Label?: string;
    }[];
    MaxFilterConditions?: number;
    RowStyleRules?: GridStyleRule[];
    SummaryMode?: "None" | "Filtered" | "All" | "Server";
    SummaryLabel?: string;
    SummaryLabelField?: string;
    SummaryFields?: {
        Field: string;
        Operation: "Sum" | "Average" | "Min" | "Max" | "Count";
    }[];
}

GridDataRequest

interface GridDataRequest {
    GridId: string;
    RequestId: string;
    StartRow: number;
    EndRow: number;
    Sort: {
        Field: string;
        Direction: "asc" | "desc";
    }[];
    Filter: Record<string, unknown>;
    SearchText: string;
}

GridEditState

interface GridEditState {
    HasChanges: boolean;
    ChangedRowCount: number;
    ChangedCellCount: number;
    IsEditing: boolean;
    IsSaving: boolean;
}

GridField

type GridField<R> = Extract<keyof R, string>;

GridInstance

interface GridInstance<R extends object> {
    readonly element: HTMLElement;
    update(patch: Partial<Pick<GridOptions<R>, "Columns" | "Rows" | "Config">>): void;
    setSearch(text: string): void;
    setData(rows: R[]): void;
    getSelectedRows(): R[];
    clearSelection(): void;
    selectPage(): void;
    applyRowValues(ids: (string | number)[], values: Partial<R>, options?: {
        /** Defaults to true for compatibility. False emits only the batch change event. */
        EmitCellEvents?: boolean;
    }): GridEditState;
    applyCells(cells: {
        RowId: string | number;
        Field: GridField<R>;
        Value: unknown;
    }[], options?: {
        EmitCellEvents?: boolean;
    }): GridEditState;
    previewPaste(text: string, rowId: string, field: GridField<R>): GridPastePreview;
    applyPaste(token: string): GridEditState;
    undo(): GridEditState;
    redo(): GridEditState;
    getFocusedCell(): {
        RowId: string;
        Field: string;
    } | null;
    getCellRange(): {
        RowIds: string[];
        Fields: string[];
    } | null;
    focusCell(rowId: string, field: string): void;
    getHistoryState(): {
        CanUndo: boolean;
        CanRedo: boolean;
    };
    getRows(scope?: GridScope): R[];
    summarize(options?: GridSummaryOptions): GridSummary;
    exportXlsx(options?: {
        FileName?: string;
        Scope?: GridScope;
        SheetName?: string;
    }): void;
    getNamedViews(): GridNamedView[];
    setNamedViews(views: GridNamedView[]): void;
    requestSaveView(name: string, scope?: "Personal" | "Team", key?: string): void;
    mountWorkbench(host: HTMLElement): () => void;
    getView(): GridView;
    /** Null clears grouping and pivot and returns to Records. */
    setReport(report: GridReport | null): GridReport;
    applyView(view: GridView): GridView;
    getColumnLayout(): GridColumnLayout;
    applyColumnLayout(layout: GridColumnLayout): GridColumnLayout;
    resetFilters(): void;
    fitColumns(): void;
    autoSizeColumns(): void;
    /** Commit the active editor and deliver pending edits without starting a save. */
    flushEdits(): Promise<GridEditState>;
    beginSave(): Promise<GridSaveRequest<R>>;
    completeSave(token: string, rows: R[]): R[];
    failSave(token: string, errors?: GridSaveError[]): GridEditState;
    cancelChanges(): Promise<GridEditState>;
    getEditState(): GridEditState;
    completeDataRequest(requestId: string, rows: R[], total: number, summary?: Record<string, number | null>): boolean;
    failDataRequest(requestId: string, message: string): boolean;
    retryLoading(): void;
    setColumnVisible(field: GridField<R>, visible: boolean): void;
    setRowExpanded(rowId: string, expanded: boolean): void;
    exportCsv(options?: {
        FileName?: string;
        OnlySelected?: boolean;
    }): void;
    destroy(): void;
}

GridNamedView

interface GridNamedView {
    Key: string;
    Name: string;
    Scope: "Personal" | "Team";
    ViewJson: string;
}

GridPastePreview

interface GridPastePreview {
    Token: string;
    RowCount: number;
    ColumnCount: number;
    Changes: {
        RowId: string;
        Field: string;
        OldValue: unknown;
        Value: unknown;
    }[];
    Errors: {
        Row: number;
        Column: number;
        Message: string;
    }[];
}

GridReport

interface GridReport {
    Display: "Records" | "Grouped" | "Chart";
    Options: GridSummaryOptions | null;
}

GridSaveError

interface GridSaveError {
    RowId: string;
    Field: string;
    Code: string;
    Message: string;
}

GridSaveRequest

interface GridSaveRequest<R> {
    SaveToken: string;
    Rows: R[];
    Changes: GridChange[];
}

GridScope

type GridScope = 'Filtered' | 'Selected' | 'All';

GridStyleRule

interface GridStyleRule {
    Field?: string;
    Operator: "equals" | "notEqual" | "greaterThan" | "greaterThanOrEqual" | "lessThan" | "lessThanOrEqual" | "inRange" | "blank" | "notBlank" | "contains" | "notContains" | "startsWith" | "endsWith";
    Value?: string;
    ValueTo?: string;
    Color?: ComponentColor;
}

GridSummary

interface GridSummary {
    Scope: GridScope;
    HasDrafts: boolean;
    GroupFields: string[];
    PivotField: string;
    ValueField: string;
    Operation: string;
    RowCount: number;
    PivotValues: unknown[];
    Groups: {
        Values: unknown[];
        RowCount: number;
        ValuesByPivot: (number | null)[];
    }[];
}

GridSummaryOptions

interface GridSummaryOptions {
    Scope?: GridScope;
    GroupFields?: string[];
    PivotField?: string;
    ValueField?: string;
    Operation?: 'Count' | 'Sum' | 'Average' | 'Min' | 'Max';
}

GridView

interface GridView {
    Version: 1;
    ColumnLayout: GridColumnLayout;
    Filter: Record<string, unknown>;
    Sort: {
        Field: string;
        Direction: 'asc' | 'desc';
    }[];
    SearchText: string;
    PageSize: number;
    RowHeight: number;
    ShowFloatingFilters: boolean;
    Report?: GridReport;
}

Events0No events yet.View events

Interact with an example to see its events.