Skip to content

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
None16Renders correctly without a line of JS.Badge, Button, Grid, Separator, Skeleton
The browser does it2Built on a native primitive: <dialog>, popover, <input>.Modal, Drawer
Behavior29Core toggles an attribute, the ARIA, and a class.Tabs, Accordion, Pagination, Tooltip
Full interaction9Focus, 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.

html
<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 panelAccordion, Collapsibledata-ts-accordion
TabsTabsdata-ts-tabs
Radio-style groupSegmentedControldata-ts-segmented
Value or span within a rangeSliderdata-ts-slider
DismissBanner, Tagdata-ts-dismissible
Show or hide a blockBreadcrumbs, NavBardata-ts-toggle
Copy to clipboardCodedata-ts-copy
Glow that follows the pointerCarddata-ts-spotlight
Active section on scrollTocdata-ts-scrollspy
Fallback when the image failsAvatardata-ts-avatar
Increase and decreaseNumberInputdata-ts-number
Drag filesFileUploaddata-ts-file-upload
Anchored floating elementTooltipdata-ts-tooltip-root
Floating element with the Popover APIPopoverpopovertarget + popover
PaginatePaginationdata-ts-pagination
Option listSelect, Comboboxdata-ts-listbox
Action searchCommandPalettedata-ts-command-palette
MenuMenu, ContextMenudata-ts-menu
CalendarDatePickerdata-ts-date-picker
Sort and virtualizeTabledata-ts-table
Collapse navigationSidebardata-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.

js
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
});
Core uses event delegation—a handful of listeners cover the whole document. HTML that shows up later—brought in by 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.

html

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.

html

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 the aria-expanded of its trigger and Core follows. That change doesn’t fire ts: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. With taisho generate and content there’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, plus print:hidden and print:block. The rest (focus:, disabled:, group-…:…) is written by taisho generate when you use it. See Variants. Dark mode doesn’t need a variant—it comes from the theme.