Get started with TypeScript

Start with the runnable example

Download and extract the starter ZIP, then run these commands inside the extracted folder. Node.js 22.12+ is required; Node 24 is recommended.

npm ci
npm run dev

Open http://127.0.0.1:3362. Choose any of the 28 components. The starter contains the library tarball, its lockfile, and a complete TypeScript example for each component. Run npm run build to type-check and bundle the examples.

To try a component without installing anything, open its Code tab. Each live preview runs the same TypeScript example included in the starter ZIP.

Add BluUI to an existing application

npm install https://bluui.blutekmedia.com/downloads/bluui-web-0.2.2.tgz

This command installs our versioned archive. @bluui/web is not published to the npm registry yet. The archive includes ES modules, TypeScript declarations, source files, and styles.

<div id="save-button"></div>

import '@bluui/web/styles.css'
import { createButton } from '@bluui/web'

const host = document.querySelector<HTMLElement>('#save-button')!
const button = createButton(host, {
  Label: 'Save changes',
  Color: 'Primary',
  Variant: 'Filled',
}, {
  Click: () => console.log('Save requested'),
})

button.update({ IsDisabled: true })
// During page or framework cleanup:
// button.destroy()

Options and callback arguments are typed. Use arrays and objects for structured values such as Nodes, Cards, SelectedKeys, and Filter. The web adapter handles the native runtime’s JSON conversion.

AdonisJS + Edge

1. Install the archive in your AdonisJS project.
2. Put the host element in an Edge view.
3. Import the CSS and component from your Vite browser entry, such as resources/js/app.ts.
4. Load that entry with Edge’s @vite(['resources/js/app.ts']) directive.
5. Mount after the host is connected. Dispose the instance when its view is removed.

The component runs in the browser. Your AdonisJS controllers own authentication, validation, and database requests. Do not call a DOM factory inside a server controller.

Load BluGrid when needed

import '@bluui/web/styles.css'
import '@bluui/web/grid.css'
import { createGrid } from '@bluui/web/grid'

interface Customer { Id: number; Name: string }
const grid = createGrid<Customer>(
  document.querySelector<HTMLElement>('#customers')!,
  {
    RowKeyField: 'Id',
    Columns: [{ Field: 'Name', Header: 'Customer', IsEditable: true }],
    Rows: [{ Id: 1, Name: 'Atlas Labs' }],
    Config: { Height: '360px' },
  },
)

Add <div id="customers"></div> to your view. Grid is a separate import so core-only applications do not load its engine. The package includes AG Grid Community and its license notices.

State, cleanup, and backend integration

Each factory returns element, update(partialOptions), and destroy(). Instances keep their selection and layout state and report changes through callbacks. Explicit updates replace the supplied values. Card and Splitter accept DOM nodes for content slots.

Grid saving uses beginSave(), followed by completeSave(token, rows) or failSave(token, errors). Kanban emits SaveRequested and expects a matching acknowledgement through update(). A rejected save retains drafts.

UploadManager uses an application-owned HTTPS multipart endpoint and supports request headers for CSRF. The starter's upload endpoint is development-only and discards files. React, Vue, and Svelte consumers can mount these DOM factories through their browser lifecycle; this release does not include JSX components.

Find a working component example

Every component page now has a Code tab with a live preview, the matching starter source, a source download, and TypeScript interfaces. The API tab continues to describe the native OutSystems Block, explicitly labeled.