DEV Community: omkar sahu

Accessible React Modal: Focus Trap and Escape Key

omkar sahu — Fri, 16 Oct 2026 15:53:07 +0000

Updated 7 October 2026. We ran every behaviour described here in Chromium, Firefox and WebKit, with oks-ui 1.4.1 and Playwright 1.63. The claims held, with two differences in WebKit that are explained below. The full results are in the table near the end.
A modal dialog is a small box on screen, but for keyboard and screen-reader users it changes where the whole page lives. An accessible modal has five jobs. This guide explains each one, shows how oks-ui's Modal handles it, and says what we saw when we tested it in three real browsers.

import "oks-ui/tokens.css"; // the design tokens every component stylesheet reads
import { Modal } from "oks-ui/modal";
import "oks-ui/modal.css";
import { Button } from "oks-ui/button";
import "oks-ui/button.css";

The first line loads the design tokens that every component stylesheet reads. Without it the components still render, but with fallback colours: in my test a danger button came out the same blue as a primary one.

The short result

Everything this guide says about the dialog itself held in Chromium, Firefox and WebKit: 40 of 42 results passed.
The two that differ are both in WebKit, the engine behind Safari, and both are about focus. Tab skips buttons there by default, and focus returns to the page body instead of the button if the dialog was opened with a mouse click.
Across 12 repeated runs in each browser (168 Tab presses each), focus never reached a control on the page behind the dialog. ## Job 1: tell assistive technology what it is A dialog needs role="dialog", aria-modal="true" and an accessible name, usually its title. oks-ui's Modal sets all three from its props. For confirmations that interrupt the user and need an answer, the correct role is alertdialog:

<Modal
  isOpen={open}
  onClose={() => setOpen(false)}
  role="alertdialog"
  title="Delete this project?"
  actions={
    <>
      <Button variant="bordered" onPress={() => setOpen(false)}>Cancel</Button>
      <Button color="danger" onPress={deleteProject}>Delete</Button>
    </>
  }
>
  The project and all its files will be removed. This can't be undone.
</Modal>

Tested: in all three browsers the dialog had role="dialog", aria-modal="true" and the name "Rename file" taken from its title, and role="alertdialog" worked the same way for the confirmation.

Job 2: move focus into the dialog

When the dialog opens, keyboard focus must move inside it. Otherwise the next Tab press walks through a page the user can no longer see.
Modal moves focus to the dialog panel by default. If one control is the natural starting point, such as the first field of a form, point initialFocusRef at it:

const nameRef = useRef<HTMLInputElement>(null);

<Modal isOpen={open} onClose={close} title="Rename file" initialFocusRef={nameRef}>
  <input ref={nameRef} defaultValue={file.name} />
</Modal>

Tested: focus moved into the dialog when it opened in all three browsers, and with initialFocusRef it landed on the field we chose.

Job 3: trap focus inside

While the dialog is open, Tab and Shift+Tab must cycle through its own controls and never escape to the page behind. This is the focus trap.
The tricky case is focus sitting on something that isn't itself tabbable, like the dialog panel after job 2. A naive trap doesn't recognise it, so Shift+Tab lets the browser move focus out of the dialog. oks-ui treats that position as a wrap point: from the panel, Shift+Tab goes to the last control and Tab to the first. (This was a real bug in oks-ui before version 1.2, fixed along with a trap that didn't attach when a modal was opened after mounting. The 1.2.0 changelog has the details.)
Tested: from the dialog panel, Tab went to the first control and Shift+Tab to the last, in all three browsers. We then pressed Tab and Shift+Tab 12 times each. In Chromium and Firefox focus cycled inside the dialog every time.

After Shift+Tab from the dialog panel, focus is on the last control, Save (Chromium).
WebKit behaved differently. By default its Tab key skips buttons, as Safari's does, so a lap through the dialog went: close button, the field, the page body, and back to the close button. Focus touched the document body once per lap, but it never reached a control on the page behind, and the next Tab brought it back into the dialog. If your dialogs are mostly buttons, check them in Safari with "Press Tab to highlight each item on a webpage" turned on, or use Option+Tab.

Job 4: close on Escape and restore focus

Escape should close the dialog. Modal does this by default; set closeOnEscape={false} only when closing by accident would lose work, and then give the user another obvious way out.
Closing is only half the job. Focus must go back to the element that opened the dialog, usually a button. Without this, focus falls to the top of the document and keyboard users lose their place. Modal remembers what was focused when it opened and returns focus there on close.
Tested: Escape closed the dialog in all three browsers, and with closeOnEscape={false} it stayed open. When we opened the dialog with the keyboard, focus returned to the button that opened it in all three.
One difference: when we opened the dialog with a mouse click in WebKit, focus returned to the page body, not the button. Safari does not give a button focus when it is clicked, so there was no focused element for the dialog to go back to. Chromium and Firefox returned to the button. We have not found a workaround we trust, so we list it as a known limit. If keyboard users on Safari matter to your app, test this case.

Job 5: stop the page behind from scrolling

Scrolling the page underneath an open dialog is disorienting, especially on phones. Modal locks page scrolling while it is open. The lock is counted, so a confirmation opened on top of a drawer keeps the page locked until both are closed.
Tested: with the dialog open, the mouse wheel moved the page 0 pixels, where the same wheel movement normally scrolls it 600. Once the dialog closed, scrolling worked again. With a modal opened on top of a drawer, the page stayed locked until both were closed. This was the same in all three browsers.

Clicking outside

By default a click on the backdrop closes the dialog, which is what most people expect. For forms where a stray click would lose typed input, turn it off with closeOnOutsideClick={false}.
Tested: in all three browsers a click on the backdrop closed the dialog, and with closeOnOutsideClick={false} it did not.

All the results

Here is every check, in each browser:

14 checks in three browsers, 40 of 42 results pass.

The 30-second keyboard test

Put the mouse away and try any dialog:

Open it with the keyboard. Does focus land inside?
Press Tab repeatedly. Does focus stay inside and wrap around?
Press Shift+Tab from the very first position. Does it still stay inside?
Press Escape. Does it close, and is focus back on the button that opened it? If all four pass, the dialog works for keyboard users. With a screen reader running, also check that the title is announced when the dialog opens. We did not test screen readers for this guide. To run the same steps against your own dialogs in all three browsers, here is the script we used, trimmed to its core. Change the address and the button name for your page:

import { chromium, firefox, webkit } from "playwright";

for (const [name, type] of [["Chromium", chromium], ["Firefox", firefox], ["WebKit", webkit]]) {
  const browser = await type.launch();
  const page = await browser.newPage();
  await page.goto("http://localhost:3000/your-page");

  // Open the dialog with the keyboard, the way a keyboard user would.
  await page.getByRole("button", { name: "Open dialog" }).focus();
  await page.keyboard.press("Enter");

  const steps = [];
  for (let i = 0; i < 8; i++) {
    await page.keyboard.press("Tab");
    steps.push(
      await page.evaluate(() => {
        const dialog = document.querySelector('[role="dialog"], [role="alertdialog"]');
        const active = document.activeElement;
        if (active === document.body) return "page body";
        if (!dialog?.contains(active)) return "OUTSIDE THE DIALOG";
        return active.getAttribute("aria-label") || active.textContent.trim();
      }),
    );
  }
  console.log(name, "Tab order:", steps.join(" > "));

  await page.keyboard.press("Escape");
  await page.waitForTimeout(800);
  console.log(name, "focus after Escape:", await page.evaluate(() => document.activeElement?.textContent?.trim()));
  await browser.close();
}

For our dialog this printed, in Firefox and in WebKit:

Firefox Tab order: Close modal > File name > Cancel > Save > Close modal > File name > Cancel > Save
Firefox focus after Escape: Open basic
WebKit Tab order: Close modal > File name > page body > Close modal > File name > page body > Close modal > File name
WebKit focus after Escape: Open basic

How we tested

oks-ui 1.4.1, Playwright 1.63.0, and the Chromium, Firefox and WebKit builds that come with it.
A page with the dialogs from this guide, driven by keyboard, and by mouse where this guide says so: 14 checks in each browser.
Twelve repeated runs of 14 Tab presses in each browser, to look for anything that comes and goes.
Not tested: screen readers, phones and tablets, and how the dialog looks in other themes. See every option on the Modal component page.

Originally published at oks-ui.com.

A zero-dependency React rich text editor: what broke

omkar sahu — Thu, 15 Oct 2026 06:04:32 +0000

The oks-ui TextEditor has no dependencies besides React, and building it that way meant writing things most projects borrow: selection across blocks, undo, formatting, link safety. This post is the honest account of what broke on the way, with each problem reproduced on an old version and checked again on 1.4.1, the browsers used stated for each one, plus what the choice costs in bytes.

The rule, and what it costs

oks-ui's rule is that the package has no runtime dependencies other than React. You can check it: the published package.json of 1.4.1 has no dependencies field, and when I bundled a page that imports only the editor, the only package that ended up inside the bundle was oks-ui itself. React stays external.
For a rich text editor that is an expensive rule. The editor folder in the source is about 13,000 lines of TypeScript and CSS, backed by about 5,500 lines of unit tests and more than 100 browser tests that run in Chromium, Firefox and WebKit. The first version landed on 21 July 2026 and the folder has had 63 commits since. Most of those commits are the fixes below.

How it is built

A document is plain data, an array of blocks, and you own it:

"use client";
import { useRef, useState } from "react";
import "oks-ui/tokens.css";
import { TextEditor, blocksFromMarkdown, type Block, type TextEditorHandle } from "oks-ui/text-editor";
import "oks-ui/text-editor.css";
import { Button } from "oks-ui/button";
import "oks-ui/button.css";

declare function save(markdown: string): void;

export function Notes({ saved }: { saved: string }) {
  const [blocks, setBlocks] = useState<Block[]>(() => blocksFromMarkdown(saved));
  const editor = useRef<TextEditorHandle>(null);
  return (
    <>
      <TextEditor ref={editor} label="Notes" value={blocks} onChange={setBlocks} />
      <Button color="primary" onPress={() => save(editor.current!.toMarkdown())}>Save</Button>
    </>
  );
}

That compiles under TypeScript 7 in strict mode against oks-ui 1.4.1. Each block is an object with an id, a type, props, content (runs of text with styles, or links) and children.
On screen, each line of text is its own editable box. That keeps typing native and cheap, and it is also the root of most of what broke: the browser's own selection, undo and formatting all stop at the edge of one box, so anything that crosses a block has to be built by hand. The editor keeps its own selection layer across blocks and draws it with the CSS Custom Highlight API, falling back to tinted blocks where that is missing.

What broke, measured

I rendered the same test page with oks-ui 1.1.2, 1.2.2 and 1.4.1 and ran the same steps in Chromium, Firefox and WebKit (the link row in Chromium only; the footnote in the table says where the browsers differed):

A document that arrives after the editor

value used to be read once, when the editor mounted. Load a saved document after that, reset a form, or switch records, and the old content stayed on screen. The only workaround was to remount with a key. In 1.4.1 a new value from outside replaces the content and becomes the undo starting point, while the usual value={blocks} onChange={setBlocks} loop, and a parent that passes an equal copy of the same content, leave the caret and the undo history alone.
A neighbouring bug: value={[]} rendered no blocks at all, so there was nothing to click or type into. It now starts with one blank paragraph.

Selection that stopped at the edge of a block

Because every line is its own box, a drag across blocks could only select whole blocks, and the keyboard could not leave a block at all. In 1.4.1, Shift plus the arrow keys at the edge of a line, a mouse drag from one block into another, Shift plus click, and Ctrl or Cmd plus A pressed twice all select across blocks, and typing, Backspace, Enter, cut, copy, paste and the formatting buttons then act on the whole selection.

Saved links that run code

A document can come from a database, so a block's URL cannot be trusted just because the editor put it there. I saved a document with three blocks whose address was a javascript: URL (a text link, a bookmark card and a file card), rendered it read-only on React 18 and clicked each one. In 1.1.2 all three ran their code. In 1.2.2 the bookmark and the file card still did. In 1.4.1 no such link is rendered: links allow only web, mail, phone, in-page and relative addresses, and media allows web, blob:, relative and inline raster images.
A caution that I only learned by testing: on React 19 the older versions looked safe, because React replaces a javascript: address with a harmless one itself. If you are on React 19 you were protected by React, not by the editor, and if you are on React 18 you were not.

Typing in a long document

Typing used to re-render every block and copy the whole document for undo on each keystroke. Rows are now memoised and undo shares the blocks that did not change. I measured one typed character in the middle of a document, wall time including layout, in headless Chromium:

At 1,500 lines that is 28.5 ms in 1.1.2 and 6.7 ms in 1.4.1; at 5,000 lines, 97.6 ms against 24.4 ms. Version 1.2.2 was no better than 1.1.2 here, so the improvement arrived after 1.2.2 (the changelog lists it under 1.4.1; I did not measure 1.3.x). These are timings on my Mac, so read the ratios and not the milliseconds. The changelog quotes larger figures (about 355 ms to 52 ms at 1,500 lines) because it measures only React's own work per keystroke and leaves out layout.

Formatting without `document.execCommand`

Until 1.4.1 bold, italic, links and the other formats were applied with document.execCommand, which MDN marks as deprecated. Version 1.4.1 applies them to the document data instead, inside whichever line holds the selection, table cells and toggles included, and then restores the selection.
I expected to be able to show a cross-browser difference here and could not. Bold on a selected word produced <b>world</b> in Chromium, Firefox and WebKit on 1.2.2, and <strong>world</strong> on 1.4.1. The stored data was identical in every case, and a format chosen at a bare caret applied to the next typed characters in both versions. So the honest reason for the change is the one in the design: formatting has to work across several blocks and inside table cells, which a single-region browser command cannot do. A test in the repository now fails if execCommand comes back.

What it costs in bytes

I bundled a page that imports only the editor, React left external, then minified and gzipped it:

The 1.1.2 line is the whole package, because it had no per-component entry points. From 1.2.2 to 1.4.1 the editor more than doubled in JavaScript (24.5 to 55.3 KB) and its CSS grew from 4.6 to 21.5 KB. That is the price of selection across blocks, find and replace, mentions, embeds, upload progress and custom blocks. If you only need a small formatted textarea, 1.4.1 is more editor than you need.

What is still not solved

One box per line is inherent. It is what makes the typing fast and native, and it is why selection and formatting needed their own layer.
Input methods. A known limit from the project's notes, which I did not re-test for this post: composing text with an input method over a selection that crosses blocks needs a Backspace first.
Real devices. The browser tests are automated and run in desktop Chromium, Firefox and WebKit. I have not tested on a real phone, with a real screen reader, or on Safari for daily use.
Contrast. My accessibility audit found that parts of the editor, such as the Edit label and mention chips, fail the 4.5:1 contrast minimum. That is still open.
Not built: comments, merging or resizing table cells, and real syntax grammars for code blocks. ## Try it The Text editor component page has every prop and a live editor. For what else changed in the same release, see the oks-ui 1.2 notes.

Originally published at oks-ui.com.

React Modal guide: sizes, closing and backdrop, tested

omkar sahu — Tue, 13 Oct 2026 02:41:21 +0000

Updated 9 October 2026. I built every example from the first version of this guide into a test page with oks-ui 1.4.1 and checked each claim in Chromium, Firefox and WebKit. The behaviour it describes held. Three details needed correcting, and two of them are traps in units: backgroundOpacity is a percentage from 0 to 100, not a fraction, and animationDuration is in seconds, not milliseconds. And dismissible={false} does not make a dialog "must be answered" on its own. The results are in a table near the end.
A modal is a box that takes over the screen until the user deals with it. Used well it keeps people in their flow; used badly it traps them. This guide covers everything oks-ui's Modal does and when to reach for something else.

import "oks-ui/tokens.css"; // the design tokens every component stylesheet reads
import { Modal } from "oks-ui/modal";
import "oks-ui/modal.css";
import { Button } from "oks-ui/button";
import "oks-ui/button.css";

The shape of a modal

Modal is controlled: you own the open state.

const [open, setOpen] = useState(false);

<Button color="primary" onPress={() => setOpen(true)}>Invite people</Button>

<Modal
  isOpen={open}
  onClose={() => setOpen(false)}
  title="Invite people"
  actions={
    <>
      <Button variant="bordered" onPress={() => setOpen(false)}>Cancel</Button>
      <Button color="primary" onPress={send}>Send invites</Button>
    </>
  }
>
  Anyone you invite can read and comment on your posts.
</Modal>

title renders the heading that names the dialog for screen readers, and actions is the row at the bottom. I checked both: the dialog had role="dialog" and aria-modal="true", and its accessible name was "Invite people", taken from the title. In the actions row, Cancel sat to the left of "Send invites", which was at the right-hand end, so put the confirming action last, where people expect it. The dialog also has a close button in its corner, named "Close modal" by default; closeLabel changes that text.

Sizes

size takes xs, sm, md (the default), lg, xl and full. You can also pass a number of pixels or any CSS width. In a 1400 pixel wide window the dialogs came out at 320, 420, 640, 860 and 1100 pixels for the first five, and as wide as the window for full. A number worked as written (500 gave 500 pixels), and so did a CSS width ("50vw" gave 700).

Confirmations: sm. A short question does not need a wide box.
Forms: md.
Tables or previews: lg and up, but consider a page instead. ## Confirmations For a question that interrupts the user and needs an answer, use role="alertdialog" and name the thing in the title:

<Modal
  isOpen={open}
  onClose={close}
  role="alertdialog"
  size="sm"
  title="Delete “Q3 report”?"
  actions={
    <>
      <Button variant="bordered" onPress={close}>Cancel</Button>
      <Button color="danger" onPress={remove}>Delete</Button>
    </>
  }
>
  The file and its history are removed. This can't be undone.
</Modal>

Write what will happen, not "Are you sure?". In my test the role was alertdialog, the accessible name was the full title including the file name, the box was 420 pixels wide, and focus landed on the dialog itself when it opened. The message text is not linked to the dialog with aria-describedby, so a screen reader will announce the title but not necessarily the sentence under it.

Forms inside a modal

Two changes make a form dialog behave:

<Modal
  isOpen={open}
  onClose={close}
  title="New project"
  closeOnOutsideClick={false}
  initialFocusRef={nameRef}
  actions={
    <>
      <Button variant="bordered" onPress={close}>Cancel</Button>
      <Button color="primary" isLoading={saving} onPress={save}>Create</Button>
    </>
  }
>
  <input ref={nameRef} />
</Modal>

closeOnOutsideClick={false} stops a stray click from losing what someone typed, and initialFocusRef puts the cursor in the first field. I confirmed both: focus went to the input when the dialog opened, a click outside the box did nothing, and Escape still closed it.

Controlling how it closes

closeOnEscape (default on): leave it on; Escape is what people press. With false, Escape did nothing.
closeOnOutsideClick (default on): turn off for forms.
dismissible={false} hides the close button. The first version said this was "for a dialog that must be answered". It is not enough for that. I turned it on and pressed Escape, and the dialog closed; I clicked outside, and it closed. Only the corner button disappeared. For a dialog that really must be answered, set all three: dismissible={false}, closeOnEscape={false} and closeOnOutsideClick={false}, and never without a visible action that closes it. ## Appearance backdrop passes options through to the overlay, and blur and backgroundOpacity adjust how much of the page shows through. I tried them both ways, as props on Modal and inside backdrop={{ ... }}, and the result was identical. Here is what the values mean, because two of them are easy to get wrong:
blur takes true, false, "sm", "md", "lg" or a number of pixels. The default was 8 pixels and "lg" gave 12.
backgroundOpacity is a percentage from 0 to 100, not a fraction. The default is 80. I passed 0.8, expecting 80 percent, and got 0.8 percent: the page behind was barely dimmed. Pass 60 for 60 percent.
animationDuration is in seconds, from 0 to 10, not milliseconds. The default is 0.3. I passed 900, expecting 900 milliseconds, and it was clamped to the maximum of 10 seconds, so the dialog took ten seconds to settle. Pass 0.6 for 600 milliseconds; that gave a duration of 600ms in the overlay's settings.
animationType takes "fade", "zoom", "slideUp", "slideDown", "slideLeft" or "slideRight". Note the camel case.

<Modal blur="lg" backgroundOpacity={60} animationDuration={0.6} animationType="slideUp" /* ... */ />

Both animation props respect a reader's "reduce motion" setting. With prefers-reduced-motion on, the dialog appeared with no movement at all, in all three browsers, even with the duration set.

Backdrop settings, and a dialog with dismissible={false}.

What it handles for you

Focus moves into the dialog when it opens and is trapped while it is open, Escape closes it, focus returns to the button that opened it, and the page behind stops scrolling. The dialog carries role="dialog", aria-modal="true" and its title as the accessible name.
I checked these again in the test page. When opened with the keyboard, focus was inside the dialog, a mouse wheel over the page did not scroll it, and closing put focus back on the opening button, in all three browsers. The accessible modal post tests the focus trap in detail, including a case in Safari: when the dialog is opened with a mouse click, focus returns to the page and not to the button.

When not to use a modal

Long forms. A dialog that scrolls is a page in disguise. Use a page.
Anything a user might want to link to or refresh. Modals have no address.
On phones, for anything but a short confirmation. A Drawer sliding from the bottom feels more natural and leaves more room. With position="bottom" it came up as a full-width sheet from the bottom edge.
Success messages. A toast says "Saved" without asking the user to dismiss it. Mine left on its own after about six seconds, and it has a close button for people who want it gone sooner. It needs a ToastProvider rendered once, as the settings page post explains. ## Results

What I measured.

Check your own dialog

This script opens your dialog with the keyboard and reports what it does: its role and name, whether it has a close button, whether the page scrolls behind it, whether an outside click and Escape close it, and where focus goes afterwards. Install playwright first.

// npm i -D playwright
// node check-dialog.mjs http://localhost:3000/page "#open-button"
import { chromium, firefox, webkit } from "playwright";

const [url, opener] = process.argv.slice(2);
const DIALOG = '[role="dialog"], [role="alertdialog"]';

for (const [name, type] of [["Chromium", chromium], ["Firefox", firefox], ["WebKit", webkit]]) {
  const browser = await type.launch();
  const page = await (await browser.newContext({ viewport: { width: 1200, height: 800 } })).newPage();
  const result = [];
  await page.goto(url);
  await page.locator(opener).focus();
  await page.keyboard.press("Enter");
  await page.waitForSelector(DIALOG);
  await page.waitForTimeout(800); // let the entrance animation finish

  const info = await page.evaluate((sel) => {
    const dialog = document.querySelector(sel);
    const named = dialog.getAttribute("aria-label") || document.getElementById(dialog.getAttribute("aria-labelledby") || "")?.textContent;
    const close = [...dialog.querySelectorAll("button")].find((b) => /close/i.test(b.getAttribute("aria-label") || b.textContent));
    return { role: dialog.getAttribute("role"), modal: dialog.getAttribute("aria-modal"), name: named?.trim() || null, closeButton: close ? (close.getAttribute("aria-label") || close.textContent.trim()) : null, focusInside: dialog.contains(document.activeElement) };
  }, DIALOG);
  result.push(`role=${info.role}, aria-modal=${info.modal}, name=${JSON.stringify(info.name)}, close button=${JSON.stringify(info.closeButton)}, focus inside=${info.focusInside}`);

  await page.mouse.move(10, 400);
  await page.mouse.wheel(0, 500);
  await page.waitForTimeout(300);
  result.push(`page scrolls behind it: ${(await page.evaluate(() => window.scrollY)) > 0}`);

  await page.mouse.click(5, 5); // outside the dialog
  await page.waitForTimeout(900);
  const closedByOutside = (await page.locator(DIALOG).count()) === 0;
  result.push(`outside click closes: ${closedByOutside}`);

  if (closedByOutside) { await page.locator(opener).focus(); await page.keyboard.press("Enter"); await page.waitForSelector(DIALOG); await page.waitForTimeout(800); }
  await page.keyboard.press("Escape");
  await page.waitForTimeout(900);
  const closedByEscape = (await page.locator(DIALOG).count()) === 0;
  result.push(`Escape closes: ${closedByEscape}`);
  result.push(`focus returns to the opener: ${await page.evaluate((o) => document.activeElement === document.querySelector(o), opener)}`);

  console.log(`${name}:\n  ${result.join("\n  ")}`);
  await browser.close();
}

On a dismissible={false} dialog it printed close button=null and then outside click closes: true and Escape closes: true, which is how I noticed the problem.
Try every prop on the Modal component page.

Limits

I tested one dialog layout in a 1400 pixel window. Dialogs taller than the window, nested dialogs, and dialogs that open other dialogs were not tested here.
The animation checks measured the dialog's position over time in desktop browsers. I did not test on a phone.
I did not test with a screen reader. I checked the attributes it reads, not what it says.
Opening with a mouse in Safari returns focus to the page and not the button, as the accessible modal post describes.

Originally published at oks-ui.com.

Build a file upload field in React, tested in three browsers

omkar sahu — Mon, 12 Oct 2026 01:47:50 +0000

Updated 9 October 2026. I built every example from the first version of this post as a real project and ran it in Chromium, Firefox and WebKit, with oks-ui 1.4.1, TypeScript 7 in strict mode and Playwright 1.63. Several things in the first version were wrong, and one of them meant its main example enforced nothing: the maxFileSize and maxFiles props shown in section 3 are ignored by FormFieldSet. The fixes are below, with the gaps I found in oks-ui itself and a table of results near the end.
File uploads look simple until you handle the real cases: someone drops a 40 MB video into an avatar picker, or picks a PDF where you wanted a photo. This tutorial builds an upload field that handles those politely.

import "oks-ui/tokens.css"; // the design tokens every component stylesheet reads
import { FormFieldSet } from "oks-ui/form-field-set";
import "oks-ui/form-field-set.css";
import "oks-ui/modal.css"; // needed when the field has multiple files: its file list opens in a dialog

The field in four states.

1. A basic file field

The value is an array of the browser's own File objects:

const [files, setFiles] = useState<File[]>([]);

<FormFieldSet
  type="file"
  name="attachment"
  label="Attachment"
  onChange={(v: unknown) => setFiles(v as File[])}
/>

This type-checks, and choosing a file gave an array with one File in it, with its real name and size.

2. Drag and drop

ui="dropzone" turns the field into a drop area, with your own wording:

<FormFieldSet
  type="file"
  name="attachment"
  label="Attachment"
  ui="dropzone"
  isDroppable
  dropLabel="Drop your file here"
  dropHelperText="or click to browse — PDF or PNG, up to 5 MB"
  browseLabel="Choose a file"
/>

All three labels showed up as written, and dropping files onto the area selected them in all three browsers. Without the labels the area says "Choose a file or drag & drop it here". Note that dropHelperText is only text: writing "PDF or PNG, up to 5 MB" there enforces nothing. The next section is about enforcing it.
Keep the click-to-browse path. Drag and drop is impossible on a phone and awkward with a keyboard. I found a problem with it, though. The hidden file input that catches the click only covers the top strip of the drop area, about 28 pixels of a 98 pixel box. I clicked a grid of points across the area, and only the top row opened the file chooser. Clicking the "Drop your file here" text, or the "or click to browse" line, did nothing in any of the three browsers. Keyboard users are fine: focusing the field and pressing Enter or Space opened the chooser in all three.

3. Limits that are enforced, not just written

Three settings do the work: accept for file types, maxFileSize in bytes, and maxFiles. How you pass them matters. The first version put all three on FormFieldSet as props:

<FormFieldSet
  type="file"
  name="photos"
  label="Photos"
  multiple
  accept="image/png,image/jpeg"
  maxFileSize={5 * 1024 * 1024}   // ignored
  maxFiles={4}                    // ignored
  preview="thumbnails"
  description="PNG or JPEG, up to 5 MB each, 4 files."
/>

I tested exactly that. accept worked: a .txt file was refused. maxFileSize and maxFiles did nothing: a file one byte over 5 MB was kept, and so were five files. FormFieldSet reads those two limits only from its validation rules and passes the result down, so a plain prop is overwritten with nothing. Put them in the rules:

<FormFieldSet
  type="file"
  name="photos"
  label="Photos"
  ui="dropzone"
  isDroppable
  multiple
  accept="image/png,image/jpeg"
  preview="thumbnails"
  description="PNG or JPEG, up to 5 MB each, 4 files."
  validation={{ rules: { accept: "image/png,image/jpeg", maxFileSize: 5 * 1024 * 1024, maxFiles: 4 } }}
/>

With the limits in validation.rules, a file of exactly 5 MB was kept, a file one byte over was refused, and the fifth file was refused, whether the files came from the picker or from a drop, in all three browsers. If you use the FileField component itself, imported from the same entry point, its maxFileSize and maxFiles props do work directly.
When a file is refused, the field shows a line such as "Skipped: over5mb.png (too large (max 5.00 MB))" or "Skipped: e.png (max files (4))" in the drop area. Two cautions:

Only the dropzone shows it. With the default inline field the file is refused silently: nothing is selected and nothing is said. Use ui="dropzone" if you want the person to be told.
It is not announced. The "Skipped" line is a plain <span>. It is not a live region and the input does not point at it, so a screen reader user gets no news that their file was refused. If that matters, mirror the message in your own live region. preview="thumbnails" shows picked images as small tiles with a remove button each, named "Remove small.png", and an "Add image" tile. Removing one updated the value. Always write the limits in the description too. An error is a poor substitute for knowing the rule in advance. ## 4. The same rules inside a form Inside an oks-ui Form, express the limits as validation rules so the form will not submit without a file:

<FormFieldSet
  type="file"
  name="resume"
  label="Résumé"
  accept=".pdf"
  validation={{
    rules: { required: true, accept: ".pdf", maxFileSize: 2 * 1024 * 1024 },
    message: { maxFileSize: "That file is over 2 MB — try compressing it." },
  }}
/>

Two things to know. Submitting with no file showed "This field is required" and did not submit. But the custom maxFileSize message from the first version never appeared. A 2.1 MB PDF is refused by the field as soon as it is picked, before validation runs. The field then looks empty, so on submit the person sees "This field is required", which is misleading. With ui="dropzone" they also see the "Skipped: … (too large (max 2.00 MB))" line, which is clearer. So for a form, I would add ui="dropzone" and not rely on the custom message.

5. Showing upload progress

The field can show per-file progress while you upload. Give it a function that returns each file's state:

const [progress, setProgress] = useState<Record<string, number>>({});

<FormFieldSet
  type="file"
  name="photos"
  multiple
  onChange={(v: unknown) => upload(v as File[])}
  getFileUploadState={(file) => ({
    status: progress[file.name] === 100 ? "completed" : "uploading",
    progress: progress[file.name] ?? 0,
  })}
/>

Your upload function sends each file and updates progress. I simulated that with timers. The progress bars exist, one per file, but they are not on the field itself. With several files the field says "2 files selected", and the bars live in a "Selected files" dialog that opens from the field's "View selected files" button. In it, each file showed its bytes sent, "Uploading..." with a percentage and a bar, then "Completed" when the state changed. So tell people where to look, or open that list for them.
That dialog is why oks-ui/modal.css is in the imports above. Without it I got an unstyled dialog stuck to the bottom of the window: 900 pixels wide and 386 tall in Chromium and WebKit, and in Firefox starting at 680 pixels in a 700 pixel window, which is almost entirely off screen. With the stylesheet it was a centred 640 pixel dialog with a backdrop.

6. Check the limits on the server too

Browser-side limits are a convenience, not a defence, because anything can post to your endpoint. Repeat every check on the server: the file type (by content, not just the name), the size, and how many files. Store uploads outside your web root or in object storage, and give them names you generate rather than the ones you were sent.
I tested why the first one matters. The field accepted a PNG renamed fake.pdf, because it checks the name and the type the browser reports, not the contents. A small test server that reads the first bytes of the upload accepted a real PDF and answered 415 to the renamed PNG. The same server also showed the naming point: it accepted a file named ../../etc/passwd.pdf and echoed that name straight back, because my toy server trusted it. Yours should not.

A note on accessibility

The field is a real <input type="file"> behind the drop zone, so the keyboard path works: Tab to it and press Enter or Space to open the chooser. axe-core found no problems in light mode, with a refused file showing. In dark mode the "Skipped" text measured 4.26 to 1 contrast (#e83535 on near-black), under the 4.5 to 1 that WCAG AA asks for. That is a gap in oks-ui 1.4.1 and I have noted it; nothing is released or fixed yet. I did not test with a screen reader.

Results

Every result, in all three browsers.

Check your own upload endpoint

This script posts five files straight to your upload endpoint, the way anything on the internet can, and prints the status code for each. Files that should be refused must not get a 2xx answer. It needs Node 18 or later and no packages.

// node check-upload-server.mjs http://localhost:3000/api/upload file
const [endpoint, field = "file"] = process.argv.slice(2);

// 8 bytes of PNG signature followed by padding: a PNG pretending to be a PDF.
const fakePdf = new Blob([new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, ...new Array(64).fill(0)])]);
const realPdf = new Blob(["%PDF-1.4\n1 0 obj<<>>endobj\ntrailer<<>>\n%%EOF\n"]);
const empty = new Blob([]);
const huge = new Blob([new Uint8Array(25 * 1024 * 1024)]); // 25 MB

const cases = [
  ["a real PDF (should be accepted)", realPdf, "report.pdf"],
  ["a PNG renamed .pdf (should be refused)", fakePdf, "report.pdf"],
  ["an empty file (should be refused)", empty, "empty.pdf"],
  ["a 25 MB file (should be refused if your limit is lower)", huge, "huge.pdf"],
  ["a path in the file name (should not be trusted)", realPdf, "../../etc/passwd.pdf"],
];

for (const [label, blob, name] of cases) {
  const body = new FormData();
  body.append(field, blob, name);
  try {
    const response = await fetch(endpoint, { method: "POST", body });
    console.log(`${String(response.status).padEnd(4)} ${label}`);
  } catch (error) {
    console.log(`ERR  ${label}: ${error.message}`);
  }
}

Against my toy server it printed 200 for the real PDF, 415 for the renamed PNG, the empty file and the 25 MB file, and 200 for the path in the name. The 25 MB file was refused only because its contents were not a PDF: my toy server has no size limit, and the 200 on the last line is the problem described above. Yours should refuse files that are too large and ignore the name it was sent.
See every option on the file field page.

Limits

I used small generated files, plus two large ones made of padding bytes. Real photos, very large uploads and slow connections were not tested.
Progress was simulated with timers. I did not upload to a real server with progress events.
I did not test on a phone, or with a screen reader.
I tested one browser window size, and did not test the file chooser dialog itself, only the event that opens it.

Originally published at oks-ui.com.

Build a SaaS settings page in React, tested in three browsers

omkar sahu — Fri, 09 Oct 2026 04:54:28 +0000

Updated 9 October 2026. I built the settings page from the first version of this post as a real project and ran it in Chromium, Firefox and WebKit, with oks-ui 1.4.1, TypeScript 7 in strict mode and Playwright 1.63. Most of it worked as described. Four things in the first version did not: the toast never appeared, the "type the workspace name" dialog had nowhere to type it, the save bar never went away after saving, and dark mode left the tab labels unreadable. Each is corrected below, and the results are in a table near the end.
Every product needs a settings screen, and most of them share the same shape: a few sections, a form per section, some switches, and a dangerous action at the bottom. This tutorial builds one with oks-ui.

import "oks-ui/tokens.css"; // the design tokens every component stylesheet reads
import { Tabs, Tab } from "oks-ui/tabs";
import "oks-ui/tabs.css";
import { Card } from "oks-ui/card";
import "oks-ui/card.css";
import { FormFieldSet } from "oks-ui/form-field-set";
import "oks-ui/form-field-set.css";
import { Button } from "oks-ui/button";
import "oks-ui/button.css";
import { Modal } from "oks-ui/modal";
import "oks-ui/modal.css";
import { toast, ToastProvider } from "oks-ui/toast";
import "oks-ui/toast.css";

The finished page in four states.

1. Sections as tabs

Settings grow. Tabs keep each group short enough to scan:

<Tabs aria-label="Settings" variant="underlined">
  <Tab key="profile" title="Profile">
    <ProfileSettings />
  </Tab>
  <Tab key="notifications" title="Notifications">
    <NotificationSettings />
  </Tab>
  <Tab key="danger" title="Danger zone">
    <DangerZone />
  </Tab>
</Tabs>

In all three browsers the tabs have the right roles, and the arrow keys move between them and switch the panel at once.
On a narrow screen the tabs scroll sideways instead of wrapping. I checked this with eight tabs at 320 pixels wide: they stayed on one line, the tab list was 645 to 659 pixels wide inside 288, the page itself did not scroll sideways, and pressing the arrow key through to the last tab brought it into view. With only three tabs they simply fit.
Put the open tab in the URL, for example /settings?section=notifications, so support can send someone straight to the right place and a refresh does not drop them back on Profile. Tabs takes a selectedKey and an onSelectionChange, so you control it yourself:

const [section, setSection] = useState(new URLSearchParams(location.search).get("section") ?? "profile");

const onSelect = (key: React.Key) => {
  setSection(String(key));
  const url = new URL(location.href);
  url.searchParams.set("section", String(key));
  history.replaceState(null, "", url);
};

<Tabs aria-label="Settings" variant="underlined" selectedKey={section} onSelectionChange={onSelect}>

I tested exactly this: choosing a tab changed the address, and reloading the page opened the same tab, in all three browsers. In Next.js you would read the value with useSearchParams instead of location.search. I did not test that variant.
A common mistake is to split settings into eight tabs with three fields each. Aim for the opposite: a handful of tabs, each worth opening. If a section has one switch in it, it belongs in another section.

2. The profile form

Group related fields in a card, one column on phones and two on desktop:

const ProfileSettings = () => {
  const [profile, setProfile] = useState(initial);
  const set = (key: string) => (v: unknown) => setProfile((p) => ({ ...p, [key]: String(v ?? "") }));

  return (
    <Card shadow="sm" radius="lg" style={{ padding: 24 }}>
      <div className="settings-grid">
        <FormFieldSet type="text" name="fullName" label="Full name" value={profile.fullName} onChange={set("fullName")} />
        <FormFieldSet type="email" name="email" label="Email" value={profile.email} onChange={set("email")}
          description="Used for sign-in and billing receipts." />
        <FormFieldSet type="text" name="company" label="Company" value={profile.company} onChange={set("company")} />
        <FormFieldSet type="select" name="timezone" label="Time zone" value={profile.timezone} onChange={set("timezone")}
          options={[{ label: "India (IST)", value: "Asia/Kolkata" }, { label: "UK (GMT)", value: "Europe/London" }]} />
      </div>
    </Card>
  );
};

.settings-grid { display: grid; gap: 16px; grid-template-columns: repeat(2, minmax(0, 1fr)); }
@media (max-width: 720px) { .settings-grid { grid-template-columns: 1fr; } }

This type-checks as written. Each label is connected to its input, and the description under the email field is linked to it with aria-describedby, so a screen reader reads it with the field. The grid changed from two columns to one under 720 pixels.

3. Switches for preferences

A preference that takes effect immediately belongs on a switch, not behind a save button:

<FormFieldSet type="switch" name="productUpdates" label="Product updates"
  description="A monthly email about new components." />
<FormFieldSet type="switch" name="commentReplies" label="Replies to my comments" />

Give every switch a description. "Product updates" alone does not tell anyone what they will receive. The switches have role="switch" and Space toggles them. In this example they are not connected to anything: wire onChange to your own save call. I tested the markup and the keyboard, not a save call.

4. A save bar that only appears when needed

Nothing is more annoying than a save button you cannot tell is active. Track whether anything changed, and show the bar only then. The first version compared against a constant, so after a successful save the bar stayed on screen forever. Keep the last saved copy in state and update it when saving succeeds:

const [saved, setSaved] = useState(initial);
const dirty = JSON.stringify(profile) !== JSON.stringify(saved);

const save = async () => {
  setSaving(true);
  await api.saveProfile(profile);
  setSaved(profile); // the new baseline: the bar goes away
  setSaving(false);
  toast.success("Settings saved");
};

{dirty && (
  <Card className="save-bar" radius="none" shadow="lg">
    <span>You have unsaved changes</span>
    <div className="save-bar-actions">
      <Button variant="bordered" onPress={() => setProfile(saved)}>Discard</Button>
      <Button color="primary" isLoading={saving} onPress={save}>Save changes</Button>
    </div>
  </Card>
)}

The first version said "pin it to the bottom" and gave no CSS. This is what I used, and why:

.save-bar { flex-direction: row; position: fixed; inset: auto 0 0 0; z-index: 10;
  justify-content: space-between; align-items: center; gap: 12px; padding: 12px 16px; }
.save-bar-actions { display: flex; gap: 8px; }

Two details. I render the bar with Card so it gets the surface colour, border and text colour from the tokens, which also makes it work in dark mode. And Card stacks its content in a column, hence the flex-direction: row. A fixed bar covers the end of the page, so add bottom padding to the page while the bar is showing. I used 96 pixels; with it, the last field could always be scrolled clear of the bar at a 380-pixel-tall window.
Discard put the fields back and removed the bar, and Save showed the button's loading state, in all three browsers.

5. The danger zone

Destructive actions get their own section, a danger colour, and a confirmation that names the thing being deleted. The first version's dialog said "Type the workspace name to confirm" but had no field to type it in, and the Delete button worked without typing anything. I confirmed both in all three browsers. Here is the version that does what it says:

const [confirm, setConfirm] = useState(false);
const [typed, setTyped] = useState("");

<Card shadow="sm" radius="lg" style={{ padding: 24, borderColor: "var(--oks-color-danger-200)" }}>
  <h3>Delete this workspace</h3>
  <p>Everything in it is removed, including your posts and files. This can't be undone.</p>
  <Button color="danger" onPress={() => setConfirm(true)}>Delete workspace</Button>
</Card>

<Modal
  isOpen={confirm}
  onClose={() => setConfirm(false)}
  role="alertdialog"
  title="Delete this workspace?"
  actions={
    <>
      <Button variant="bordered" onPress={() => setConfirm(false)}>Cancel</Button>
      <Button color="danger" onPress={remove} isDisabled={typed !== workspace.name}>Delete</Button>
    </>
  }
>
  Type the workspace name to confirm. This removes all of its data.
  <FormFieldSet type="text" name="confirmName" label="Workspace name" value={typed}
    onChange={(v: unknown) => setTyped(String(v ?? ""))} />
</Modal>

With this, Delete stayed disabled until the typed text matched, in all three browsers. The dialog has role="alertdialog" and its title as its accessible name; that role is the correct one for a confirmation that interrupts the user. The --oks-color-danger-200 token exists in tokens.css.

6. Feedback after saving

Use a toast, not an alert that pushes the page around. The first version showed toast.success("Settings saved") and nothing else, and with only that, nothing appears: I tried it in all three browsers and the page stayed silent. The toast needs a ToastProvider rendered once, near the top of your app:

import { toast, ToastProvider } from "oks-ui/toast";
import "oks-ui/toast.css";

root.render(
  <ToastProvider>
    <App />
  </ToastProvider>,
);

toast.success("Settings saved");

7. Do not lose someone's edits

A settings page is the classic place to lose work: a person edits three fields, clicks a nav link, and the changes are gone with no warning. Guard the exit while the form is dirty:

useEffect(() => {
  if (!dirty) return;
  const warn = (e: BeforeUnloadEvent) => e.preventDefault();
  window.addEventListener("beforeunload", warn);
  return () => window.removeEventListener("beforeunload", warn);
}, [dirty]);

This worked in all three browsers: closing the page after an edit raised the browser's "leave site?" prompt, and closing an untouched form did not. Browsers only show the prompt if the person has interacted with the page, which an edit counts as. That covers closing the tab. For in-app navigation, intercept the router's route change and show the same kind of confirmation dialog. I did not test router interception.

Dark mode: set the page text colour

data-theme="dark" changes the components, but the text you write yourself, the page heading and the tab labels, takes its colour from the page. tokens.css does not set one. On my page in dark mode the tab labels came out black on a near-black background, a contrast ratio of 1.06 to 1, and axe-core flagged them. One rule fixes it:

body { background: var(--oks-color-surface); color: var(--oks-color-neutral-900); }

With that, axe-core reported no violations in light or dark in any of the three browsers. The same token worked in both themes in my test.

What to leave out

Two things creep into settings pages and never earn their place. The first is a second confirmation on harmless actions: asking "are you sure?" before saving a display name teaches people to click through every dialog, including the one that matters. The second is an avatar uploader that silently drops a 12 MB photo; if you have one, state the limits next to it.

Results

Every result, in all three browsers.
For size, the whole page with React came to 118 KB of JavaScript and 26 KB of CSS gzipped.

Check your own unsaved-changes guard

This script types into a field, closes the page, and reports whether the browser would have asked before leaving, in each engine. Install playwright first.

// npm i -D playwright
// node unsaved-guard-check.mjs http://localhost:3000/settings "input[name=company]"
import { chromium, firefox, webkit } from "playwright";

const [url, selector] = process.argv.slice(2);

for (const [name, type] of [["Chromium", chromium], ["Firefox", firefox], ["WebKit", webkit]]) {
  const results = [];
  for (const edit of [false, true]) {
    const browser = await type.launch();
    const context = await browser.newContext({ viewport: { width: 1000, height: 800 } });
    const page = await context.newPage();
    let asked = false;
    page.on("dialog", (dialog) => {
      if (dialog.type() === "beforeunload") asked = true;
      dialog.dismiss().catch(() => {});
    });
    await page.goto(url);
    await page.click(selector); // browsers only ask after the page has had a user interaction
    if (edit) await page.keyboard.type("x");
    await page.waitForTimeout(200); // let the app notice the edit
    await page.close({ runBeforeUnload: true });
    await new Promise((resolve) => setTimeout(resolve, 400)); // the dialog event can arrive just after close()
    results.push(`${edit ? "after an edit" : "untouched"}: ${asked ? "asks before leaving" : "leaves silently"}`);
    await browser.close();
  }
  console.log(`${name}: ${results.join("; ")}`);
}

On my page it printed "untouched: leaves silently; after an edit: asks before leaving" for all three browsers.
See a finished version on the settings pattern.

Limits

I built one page with three sections and four profile fields. Larger forms, validation messages and long option lists were not tested.
The save call is simulated with a short delay. I did not test failed saves or what the bar should do when one fails.
The tab-in-URL code was tested with plain URLSearchParams and history.replaceState, not with Next.js's useSearchParams. Router interception for in-app navigation was not tested.
axe-core can only find some kinds of accessibility problem, and I did not test with a screen reader.
I tested in desktop browsers at several widths, not on real phones.

Originally published at oks-ui.com.

Reduce React Bundle Size with Per-Component Imports

omkar sahu — Wed, 07 Oct 2026 05:36:25 +0000

A component library should cost you only the components you use. In practice, importing everything from a library's main entry point often ships far more than that. This guide explains why, and how to import oks-ui so your app pays only for what it renders.

Why "just import it" can be expensive

The usual import looks harmless:

import { Button, Modal, Table } from "oks-ui";
import "oks-ui/styles.css";

Bundlers try to drop unused exports ("tree shaking"), but they can only drop code they can prove has no side effects. A stylesheet import is a side effect by definition, and a single combined stylesheet contains every component's CSS no matter which ones you use. The result in many real apps: the whole library ships. For oks-ui that is around 770 KB of JavaScript before compression and a 320 KB stylesheet — even for a page with three components.

Import each component from its own path

Since version 1.2, every oks-ui component has its own entry point and its own stylesheet:

import { Button } from "oks-ui/button";
import "oks-ui/button.css";

import { Modal } from "oks-ui/modal";
import "oks-ui/modal.css";

import { Table } from "oks-ui/table";
import "oks-ui/table.css";

The bundler has nothing to guess about: it includes the files you imported and nothing else.
Two things make this easy:

Stylesheets include their parts. oks-ui/modal.css already contains the Backdrop's styles, and oks-ui/table.css covers its empty state and loading skeleton. You never need to know what a component is made of.
Tokens stay global. Load oks-ui/tokens.css (and optionally oks-ui/utilities.css) once at the root of your app. Every component reads the same colour, spacing and radius variables. The path is the component name in kebab-case: oks-ui/button-group, oks-ui/page-title, oks-ui/form-field-set, oks-ui/text-editor. ## Next.js and Turbopack Each component's JavaScript also imports its own stylesheet, and most bundlers — webpack, Vite, Rollup, Rspack — follow that automatically. Next.js with Turbopack does not follow a stylesheet imported from inside a package, so write the .css import yourself. It's harmless elsewhere, so the simplest rule is to always write it. In the App Router, add "use client" to files that render oks-ui components. A small wrapper file per component keeps that boundary contained, so your pages can stay server components. ## Migration checklist
Replace import "oks-ui/styles.css" with oks-ui/tokens.css and oks-ui/utilities.css in your root stylesheet.
Change each from "oks-ui" import to the component's own path, and add its .css import beside it.
Search for any remaining from "oks-ui" — one leftover import can pull the whole library back in.
Open each page and look for unstyled components. A missing .css import is the only thing that can go wrong, and it is obvious on sight. Old and new imports work side by side, so you can migrate one file at a time. ## Measure it Don't trust the theory — measure before and after:
Your framework's build output lists the size of each route.
A bundle analyzer shows which packages end up in each chunk.
Lighthouse on a throttled mobile profile shows what the difference means for real users. On the oks-ui website, moving to per-component imports cut compressed CSS from 48 KB to 16 KB and JavaScript by about a fifth. Less CSS matters most on phones, because the browser can't paint the page until its stylesheets have arrived. See both import styles in the installation guide.

Originally published at oks-ui.com.

Build a sortable, selectable data table

omkar sahu — Tue, 06 Oct 2026 03:19:34 +0000

Search, sort, select, paginate — almost every admin screen needs the same data table, and almost every team ends up hand-rolling it because no single component quite covers all four. Here's the whole thing with Table, Pagination and FormFieldSet, wired together with plain React state.

1. The shape of the data

Table takes rows as plain objects and a getRowKey function — no adapter layer, no special row type.

type Row = { id: number; name: string; email: string; role: string };

const DATA: Row[] = [
  { id: 1, name: "Ada Lovelace", email: "ada@oks-ui.com", role: "Owner" },
  { id: 2, name: "Grace Hopper", email: "grace@oks-ui.com", role: "Admin" },
  { id: 3, name: "Alan Turing", email: "alan@oks-ui.com", role: "Member" },
  // ...
];

2. Search filters the rows, not the table

Table itself has no search box — it just renders whatever rows you give it. Filtering lives in your own state, one useMemo:

const [query, setQuery] = useState("");
const [page, setPage] = useState(1);

const filtered = useMemo(
  () => DATA.filter((r) => r.name.toLowerCase().includes(query.toLowerCase())),
  [query],
);

3. Sorting, selection, and the table itself

Pass sortable: true on a column and Table handles the click-to-sort interface; omit onSortChange and it sorts client-side automatically — supply it and you get the descriptor back instead, for a server-side sort. selectionMode="multiple" plus selectedKeys and onSelectionChange gets you checkboxes and an indeterminate header state for free:

const [selected, setSelected] = useState<Set<number>>(new Set());

<Table
  aria-label="Team members"
  columns={[
    { key: "name", header: "Name", sortable: true },
    { key: "email", header: "Email" },
    { key: "role", header: "Role" },
  ]}
  rows={pageRows}
  getRowKey={(r) => r.id}
  selectionMode="multiple"
  selectedKeys={selected}
  onSelectionChange={(keys) => setSelected(keys as Set<number>)}
/>

aria-label is required, not optional. Table throws in development if you skip it — a data table with no accessible name is unusable with a screen reader, so the component won't let you forget it.

4. Pagination, wired to the same filtered list

Pagination and PaginationSummary are just told the current page, the page count and the total — they don't know or care that the underlying data came from a search filter:

const PAGE_SIZE = 4;
const pageRows = filtered.slice((page - 1) * PAGE_SIZE, page * PAGE_SIZE);

<PaginationSummary page={page} pageSize={PAGE_SIZE} total={filtered.length} />
<Pagination
  page={page}
  pageCount={Math.max(1, Math.ceil(filtered.length / PAGE_SIZE))}
  onChange={setPage}
/>

Loading, empty and expanded states

Three props round out the states a real table needs: isLoading swaps in skeleton rows, emptyContent replaces the body when rows is empty (it already defaults to a sensible empty state), and renderExpandedRow adds a chevron-toggle column for a details panel under any row — no layout work required for any of the three.
Full prop reference at the Table component page, and this exact example — search, sort, select, paginate, wired end to end — as a live preview with the complete source at the data table pattern.

Originally published at oks-ui.com.

Theme oks-ui to your brand in 10 minutes

omkar sahu — Tue, 06 Oct 2026 03:12:16 +0000

oks-ui ships with a neutral default look on purpose — every colour, radius, space and shadow it renders is a plain CSS custom property, not a baked-in design opinion. That means re-theming it isn't a config file or a build step; it's a stylesheet. Here's the whole path from default to your brand, in the order that actually matters.

1. Start with the primary ramp, not just one colour

primary is the semantic role that colours your main buttons, links and focus rings. It's tempting to override just --oks-color-primary-500 and call it done, but a solid button also reads 600 for hover and 700 for pressed — override the whole ramp so those states stay coherent instead of falling back to the default orange.

:root {
  --oks-color-primary-50:  #eef2ff;
  --oks-color-primary-100: #e0e7ff;
  --oks-color-primary-500: #4f46e5;  /* your brand */
  --oks-color-primary-600: #4338ca;  /* hover */
  --oks-color-primary-700: #3730a3;  /* active / pressed */
}

Check contrast before you ship it. A solid Button or Chip puts white label text on 500 and deeper by default. Before you lock in a brand colour, check that white clears 4.5:1 against it — a vivid, light colour like a saturated yellow or orange usually won't, and needs a slightly deeper 500 to stay accessible.

2. Match your shape language

Radius is one scale, reused everywhere — cards, buttons, inputs, modals. Nudge the two or three sizes you actually see and the whole interface shifts from sharp to soft in one edit.

:root {
  --oks-radius-sm: 0.125rem;  /* chips, small controls */
  --oks-radius-md: 0.5rem;    /* the one most components default to */
  --oks-radius-lg: 0.875rem;  /* cards, modals */
}

3. Dial in density

The space scale drives padding and gaps across the library. If your product wants to feel airier or more compact than the default, nudge --oks-space-4 — it's the workhorse most components reach for.

:root { --oks-space-4: 14px; }  /* default is 16px */

4. Point neutral surfaces at your own grey

If your brand's grey isn't oks-ui's default, alias the neutral role instead of overriding a dozen individual tokens — form-field borders and muted text all read from it.

:root {
  --oks-color-neutral-100: var(--oks-palette-stone-100);
  --oks-color-neutral-500: var(--oks-palette-stone-500);
}

5. Do it again for dark mode

Dark mode is a data-theme="dark" attribute on <html>, not a second theme system — repeat the same overrides under that selector. The one thing to remember is that two tokens, --oks-color-surface and the form-field background, have light-only defaults, so your app has to supply the dark values itself:

:root[data-theme="dark"] {
  --oks-color-primary-500: #6366f1;  /* usually a touch lighter than light mode */
  --oks-color-surface: #0a0a0a;
  --oks-form-field-bg: #171717;
}

That's the whole system — no provider, no rebuild, no JavaScript theme object. See the full token reference at Theming and dark-mode specifics at Dark mode.

Originally published at oks-ui.com.

Dark mode with no flash: the data-theme init pattern

omkar sahu — Tue, 06 Oct 2026 03:09:22 +0000

The classic dark-mode bug: a user with dark mode saved loads your page, and for one visible frame it's light — then it snaps to dark. The fix isn't complicated, but it only works if you do it in a very specific order, and most "just add a class in useEffect" implementations get that order wrong. Here's the pattern this site itself runs on, in full.

Why the flash happens at all

Server-rendered HTML has no idea what theme a returning visitor prefers — that preference lives in the browser's localStorage, which the server can't read. So the page necessarily ships with some default theme baked into the markup. If you apply the real theme in a React useEffect, that effect runs after the browser has already painted the default — hence the flash.

The fix: a synchronous script before hydration

The theme has to be applied before the browser paints anything, which means before React even loads. A plain, tiny, synchronous <script> in <head> — or as early in <body> as your framework allows — does exactly that:

(function () {
  try {
    var stored = localStorage.getItem("oks-ui-theme");
    var theme = stored === "light" || stored === "dark"
      ? stored
      : (window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light");
    document.documentElement.setAttribute("data-theme", theme);
  } catch (e) {}
})();

Three things make this work that are easy to get wrong in a rewrite:

It runs before hydration, not in an effect. In Next.js that's <Script strategy="beforeInteractive">; in a non-Next app it's a plain inline <script> placed before your stylesheet, since the attribute has to exist before the CSS that reads it is applied.
It falls back through three sources in order: an explicit stored choice, then the OS-level prefers-color-scheme media query, then a hard default. Skipping the media-query fallback means a first-time visitor with dark mode set at the OS level still sees a light flash.
It's wrapped in try/catch. localStorage throws in some locked-down or privacy-mode browser contexts — a script this early in the page load has no error boundary to catch it, so an uncaught throw here can block the rest of the page from rendering at all. ## The React side: expect the mismatch, don't fight it The script sets data-theme on <html> directly, outside React's tree — which means React's hydration will notice that attribute the server never rendered and, by default, log a mismatch warning. The fix isn't to move the logic into React, which reintroduces the flash — it's to tell React this one attribute is expected to differ:

<html lang="en" suppressHydrationWarning>
  {/* ... */}
</html>

Scope suppressHydrationWarning narrowly. Put it only on the element whose attributes the script actually touches — <html> here. Slapping it on a much larger subtree silences real hydration bugs along with the expected one.

Everything downstream is just CSS

Once data-theme="dark" is on <html>, oks-ui's tokens respond to it with an ordinary attribute selector — no React context, no re-render, no provider:

:root { --oks-color-surface: #fff; }
:root[data-theme="dark"] { --oks-color-surface: #0a0a0a; }

A toggle button just flips the attribute and writes the same key back to localStorage — no re-run of the init script needed, since the browser already has the page open.
See the full token list this responds to at Dark mode.

Originally published at oks-ui.com.

Build an Admin Dashboard in React

omkar sahu — Tue, 06 Oct 2026 02:30:34 +0000

An admin dashboard is mostly three things: a row of numbers that matter, a chart that shows the trend, and a table of recent activity. In this tutorial we build all three with oks-ui and arrange them in a layout that works from phone to desktop.

import { Card } from "oks-ui/card";
import "oks-ui/card.css";
import { Stat } from "oks-ui/stat";
import "oks-ui/stat.css";
import { Chart } from "oks-ui/chart";
import "oks-ui/chart.css";
import { Table, type TableColumn } from "oks-ui/table";
import "oks-ui/table.css";
import { Chip } from "oks-ui/chip";
import "oks-ui/chip.css";

Decide what goes on it first

The hardest part of a dashboard isn't the code, it's choosing what to show. A useful test: every number on the first screen should answer a question someone actually asks every day. "How much did we sell this week?" earns a card. "Total registered users since launch" usually doesn't, because it only ever goes up and nobody acts on it.
Keep the top row to four numbers. Show each one next to its change over a comparable period, because a number without context can't tell you whether today is good or bad. Put detail — the chart and the table — underneath, where people look once the top row has told them something is worth a closer look.

1. KPI cards

Stat shows a label, a big value, and an optional change with a direction. The direction colours the change pill and picks the arrow.

const kpis = [
  { label: "Revenue", value: "$48,210", delta: "+12.4%", trend: "up" },
  { label: "Orders", value: "1,284", delta: "+3.1%", trend: "up" },
  { label: "Refunds", value: "18", delta: "-2", trend: "down" },
  { label: "Conversion", value: "3.2%", delta: "0.0%", trend: "flat" },
] as const;

<div className="kpi-grid">
  {kpis.map((k) => (
    <Card key={k.label} shadow="sm" radius="lg" style={{ padding: 20 }}>
      <Stat label={k.label} value={k.value} delta={k.delta} trend={k.trend} />
    </Card>
  ))}
</div>

Stat also takes an icon, a help line under the value, and a spark slot for a tiny chart.

2. The revenue chart

Chart takes rows of data, the key for the x-axis, and the series to draw. Multiple series get a legend automatically.

const revenue = [
  { month: "Jan", online: 12400, store: 8200 },
  { month: "Feb", online: 13900, store: 7900 },
  { month: "Mar", online: 15100, store: 8800 },
  { month: "Apr", online: 16800, store: 9100 },
  { month: "May", online: 18200, store: 9600 },
  { month: "Jun", online: 21000, store: 10400 },
];

<Card shadow="sm" radius="lg" style={{ padding: 20 }}>
  <Chart
    type="area"
    title="Revenue"
    description="Online vs. in-store, last 6 months"
    data={revenue}
    x="month"
    series={[
      { key: "online", name: "Online" },
      { key: "store", name: "In store" },
    ]}
    height={280}
  />
</Card>

Change type to "line" or "column" and nothing else needs to change. The chart has tooltips on hover and can be browsed with the arrow keys.

3. Recent orders

Table takes column definitions and rows. A column's render function controls how a cell looks — here, a status Chip.

type Order = { id: string; customer: string; total: number; status: "Paid" | "Pending" | "Refunded" };

const STATUS_COLOR = { Paid: "success", Pending: "warning", Refunded: "default" } as const;

const columns: TableColumn<Order>[] = [
  { key: "id", header: "Order" },
  { key: "customer", header: "Customer", sortable: true },
  {
    key: "total",
    header: "Total",
    align: "end",
    sortable: true,
    render: (o) => `$${o.total.toFixed(2)}`,
  },
  {
    key: "status",
    header: "Status",
    render: (o) => (
      <Chip size="sm" variant="soft" color={STATUS_COLOR[o.status]}>{o.status}</Chip>
    ),
  },
];

<Card shadow="sm" radius="lg" style={{ padding: 20 }}>
  <Table aria-label="Recent orders" columns={columns} rows={orders} getRowKey={(o) => o.id} />
</Card>

Sortable columns sort on click, with no extra code.

4. The layout

A few lines of CSS grid make it responsive: four KPI cards in a row on desktop, two on phones.

.dashboard { display: grid; gap: 16px; }
.kpi-grid { display: grid; gap: 16px; grid-template-columns: repeat(4, minmax(0, 1fr)); }
.dashboard-main { display: grid; gap: 16px; grid-template-columns: 2fr 1fr; }

@media (max-width: 900px) {
  .kpi-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
  .dashboard-main { grid-template-columns: 1fr; }
}

Put the chart in the wider column of .dashboard-main and a smaller card — top products, or a donut chart — in the narrow one.

5. Loading states

Dashboards load data, and blank cards while waiting look broken. Table shows skeleton rows with isLoading, and Chart shows a loading overlay with the same prop:

<Table aria-label="Recent orders" columns={columns} rows={orders ?? []} getRowKey={(o) => o.id} isLoading={!orders} />
<Chart type="area" data={revenue ?? []} x="month" series="online" isLoading={!revenue} />

Dark mode

Every component here uses oks-ui's design tokens, so the whole dashboard switches to dark mode when you set data-theme="dark" on the html element — cards, chart, table and chips included.
See a complete version on the patterns page.

Originally published at oks-ui.com.

DEV Community: omkar sahu

Accessible React Modal: Focus Trap and Escape Key

The short result

Job 2: move focus into the dialog

Job 3: trap focus inside

Job 4: close on Escape and restore focus

Job 5: stop the page behind from scrolling

Clicking outside

All the results

The 30-second keyboard test

How we tested

A zero-dependency React rich text editor: what broke

The rule, and what it costs

How it is built

What broke, measured

A document that arrives after the editor

Selection that stopped at the edge of a block

Saved links that run code

Typing in a long document

Formatting without document.execCommand

What it costs in bytes

What is still not solved

React Modal guide: sizes, closing and backdrop, tested

The shape of a modal

Sizes

Forms inside a modal

Controlling how it closes

What it handles for you

When not to use a modal

Check your own dialog

Limits

Build a file upload field in React, tested in three browsers

1. A basic file field

2. Drag and drop

3. Limits that are enforced, not just written

5. Showing upload progress

6. Check the limits on the server too

A note on accessibility

Results

Check your own upload endpoint

Limits

Build a SaaS settings page in React, tested in three browsers

1. Sections as tabs

2. The profile form

3. Switches for preferences

4. A save bar that only appears when needed

5. The danger zone

6. Feedback after saving

7. Do not lose someone's edits

Dark mode: set the page text colour

What to leave out

Results

Check your own unsaved-changes guard

Limits

Reduce React Bundle Size with Per-Component Imports

Why "just import it" can be expensive

Import each component from its own path

Build a sortable, selectable data table

1. The shape of the data

2. Search filters the rows, not the table

3. Sorting, selection, and the table itself

4. Pagination, wired to the same filtered list

Loading, empty and expanded states

Theme oks-ui to your brand in 10 minutes

1. Start with the primary ramp, not just one colour

2. Match your shape language

3. Dial in density

4. Point neutral surfaces at your own grey

5. Do it again for dark mode

Dark mode with no flash: the data-theme init pattern

Why the flash happens at all

The fix: a synchronous script before hydration

Everything downstream is just CSS

Build an Admin Dashboard in React

Decide what goes on it first

1. KPI cards

2. The revenue chart

3. Recent orders

4. The layout

5. Loading states

Formatting without `document.execCommand`