Behavior
What Core’s JS does, how it hooks into the HTML, and how you find out what happens. The CSS paints; this JS makes it work.
What needs JS and what doesn’t
Of the 56 components, 18 work
without a line of JS—some because they’re presentational, others because they’re built on
browser primitives. Modal, Drawer, and AlertDialog use <dialog> and invoker commands: in browsers that ship them (Chrome 135,
Firefox 144, Safari 26.2) they open and trap focus with no JS; in the ones that don’t (Safari before 26.2,
including the 17.4 floor, and Firefox before 144) Core’s JS opens them, running the commands on the dialog.
Without that JS, the trigger doesn’t open anything there, and you need to call showModal() from your own code (see Browser support).
| How much JS | Components | What it means | Examples |
|---|---|---|---|
| None | 16 | Renders correctly without a line of JS. | Badge, Button, Grid, Separator, Skeleton |
| The browser does it | 2 | Built on a native primitive: <dialog>, popover, <input>. | Modal, Drawer |
| Behavior | 29 | Core toggles an attribute, the ARIA, and a class. | Tabs, Accordion, Pagination, Tooltip |
| Full interaction | 9 | Focus, keyboard, filtering, virtualization. | Select, Combobox, DatePicker, Table, Toast |
The contract: attributes, not classes
Behavior hooks in through data-ts-* attributes, never through
classes. That lets you change the styles, rename classes, or replace the whole CSS without
breaking anything that works.
<div data-ts-tabs>
<div role="tablist">
<button role="tab" data-ts-tabs-tab data-ts-value="resumen"
aria-selected="true" tabindex="0">Overview</button>
<button role="tab" data-ts-tabs-tab data-ts-value="facturacion"
aria-selected="false" tabindex="-1">Billing</button>
</div>
<div role="tabpanel" data-ts-tabs-panel data-ts-value="resumen">Team overview</div>
<div role="tabpanel" data-ts-tabs-panel data-ts-value="facturacion">This month's invoices</div>
</div>Components that share a gesture share the code. Collapsible behaves like a one-item Accordion, and Banner and Tag are dismissed the same way. The CSS changes, not the behavior.
| Gesture | Components | Attribute |
|---|---|---|
| Open and close a panel | Accordion, Collapsible | data-ts-accordion |
| Tabs | Tabs | data-ts-tabs |
| Radio-style group | SegmentedControl | data-ts-segmented |
| Value or span within a range | Slider | data-ts-slider |
| Dismiss | Banner, Tag | data-ts-dismissible |
| Show or hide a block | Breadcrumbs, NavBar | data-ts-toggle |
| Copy to clipboard | Code | data-ts-copy |
| Glow that follows the pointer | Card | data-ts-spotlight |
| Active section on scroll | Toc | data-ts-scrollspy |
| Fallback when the image fails | Avatar | data-ts-avatar |
| Increase and decrease | NumberInput | data-ts-number |
| Drag files | FileUpload | data-ts-file-upload |
| Anchored floating element | Tooltip | data-ts-tooltip-root |
| Floating element with the Popover API | Popover | popovertarget + popover |
| Paginate | Pagination | data-ts-pagination |
| Option list | Select, Combobox | data-ts-listbox |
| Action search | CommandPalette | data-ts-command-palette |
| Menu | Menu, ContextMenu | data-ts-menu |
| Calendar | DatePicker | data-ts-date-picker |
| Sort and virtualize | Table | data-ts-table |
| Collapse navigation | Sidebar | data-ts-sidebar |
How you find out about changes
Plain HTML has no onchange, so every change emits a ts:change event that bubbles. It’s cancelable.
If you stop it, Core doesn’t touch the DOM and the change is yours to handle. In Table, stopping it leaves
the rows as they are, but the sorted column is still marked, so the next click computes the right direction.
document.addEventListener('ts:change', (e) => {
if (e.detail.component === 'tabs') console.log('tab:', e.detail.value);
if (e.detail.component === 'pagination') cargarPagina(e.detail.page);
// e.preventDefault() → Core doesn't apply the change
});fetch or rendered by another script—works without calling init() again.Toast from the HTML or from your JS
A toast shows up when something happens, so there are two ways to trigger it. From the HTML, use a button with data-ts-toast-trigger="Text" and, optionally, data-ts-toast-variant.
From your JS, call toast(), imported from the same taisho.core.js you
load on the page, with the CDN URL. Paste the container from the example on the Toast page. It brings the icons for
each variant. Without it, Core creates one, but the toasts show up without an icon.
<script type="module">
import { toast, updateToast } from 'https://taisho.design/core/0.16.0/taisho.core.js';
toast('Saved', { variant: 'success' });
// With an action, and updating the same toast
const aviso = toast('Project deleted.', { action: { label: 'Undo', onclick: restaurar } });
updateToast(aviso, { message: 'Project restored.', variant: 'success' });
// A toast that follows a promise: loading, then success or error in the same spot
toast.promise(guardar(), { loading: 'Saving…', success: 'Saved', error: 'Save failed' });
</script>If you installed the package (npm i -D @taishods/core), the same file is imported as @taishods/core/core. For the toast to show, you need the Toast CSS
(taisho.toast.css, or the full one).
Form errors
Mark an invalid field with aria-invalid="true" on its control, and that is enough to paint it:
Input, Textarea, Select, Combobox, NumberInput, DatePicker, Checkbox, and Toggle carry it on the control; Radio, on its radiogroup. On Toggle, the error color shows when it is on. The message always goes in a ts input-hint variant-danger, inside a ts input-footer, linked with aria-describedby.
To skip writing those steps by hand, use markInvalid(field, message) and clearInvalid(field). field is the control or its root. If it already
had a hint, the error replaces it and clearing brings it back. Call it again to change the message.
<form id="new-project" novalidate>
<div class="ts input-wrapper">
<label class="ts input-label" for="name">Project name</label>
<div class="ts input size-md">
<input id="name" name="name" class="ts input-field">
</div>
</div>
<button class="ts button size-md variant-primary">Create project</button>
</form>
<script type="module">
import { markInvalid, clearInvalid } from 'https://taisho.design/core/0.16.0/taisho.core.js';
const form = document.querySelector('#new-project');
form.addEventListener('submit', (e) => {
e.preventDefault();
const { name } = form.elements;
if (!name.value.trim()) markInvalid(name, 'Give the project a name.');
else if (name.value === 'Dashboard') markInvalid(name, 'A project with that name already exists.');
else clearInvalid(name);
});
// The error goes away when the person fixes it
form.addEventListener('input', (e) => clearInvalid(e.target));
</script>The message uses Input's CSS: if you load per-component files, add taisho.input.css or use the
full one. With taisho generate it comes out on its own when your JS is in content.
Controlling it from your code
Core has no props or controlled state: state lives in the DOM, and your code reads and writes it. Three things worth knowing.
- State lives in the DOM (
aria-expanded,hidden), which is what Core reads and writes. To open or close an Accordion or a Collapsible from your code, change thearia-expandedof its trigger and Core follows. That change doesn’t firets:change, which is only for the person’s gesture. - Closed panels are in the DOM, with
hidden. They’re all there from the start: nothing creates them later. - Responsive variants are a curated set in the
static file (
taisho.full.css, the one on the CDN): display, flex, grid,gap, alignment, and width—not spacing. Withtaisho generateandcontentthere’s no such limit. Any utility comes out with any screen you write. State and print variants are a curated set too in the static file:hover:on colors, underline, and opacity, plusprint:hiddenandprint:block. The rest (focus:,disabled:,group-…:…) is written bytaisho generatewhen you use it. See Variants. Dark mode doesn’t need a variant—it comes from the theme.