StartFoundationsComponentsContent
Overview Getting started API conventions Symbols data

API conventions

Every Thykes component names things the same way. Learn the pattern once and you can guess most of an API before you look it up.

Attributes and properties

  • Settings are attributes, written in kebab-case. Each has a camelCase property: full-width in markup is fullWidth in JavaScript.
  • Boolean attributes are on when present: disabled, loading, required. They name a state, so there are no no-* attributes. To remove a default part, look for hide-*, such as hide-icon on Banner.
  • Data that markup can't hold is a property only: the rows and columns of a Data table, the nodes of a Tree, the options of a Combobox. The component's page says which ones.
  • Text that screen readers hear has an attribute, with an English default: dismiss-label, clear-label, remove-label. Set them when your interface isn't in English.

Variant, tone, treatment, shape

Four attributes change how a component looks, and each means one thing everywhere.

Attribute What it changes Examples
variant the kind or role of the component primary · secondary · outline · ghost on Button; field · filter on Select
tone the status color neutral · info · success · warning · error on Badge, Banner, Section message; neutral · danger on Button
treatment how loud the same component is subtle · solid on Badge; subtle · loud on Banner; standard · quiet on Link
shape the corners rect · round on buttons, button groups, Tab bar and Segmented control
Paid Paid Subscribe
<tk-badge tone="success">Paid</tk-badge>
<tk-badge tone="success" treatment="solid">Paid</tk-badge>
<tk-button variant="primary" shape="round">Subscribe</tk-button>

Progress bar and Progress ring use intent (accent · success · error) instead of tone, because accent means "working", not a status.

Sizes

size takes small, medium or large, and the default is medium. Each component ships the steps it needs:

Components size values What changes
Button, Icon button, Split button small · medium · large height 24 / 32 / 36px
Input, Select, Combobox and the other fields medium · large height 32 / 36px
Button group, Toggle button group small · medium · large, no default sets every button inside; unset keeps each button's own
Switch, Slider medium · small the control's scale
Progress bar small · medium bar thickness
Progress ring small · medium · large · xlarge diameter 24 / 40 / 64 / 96px
Dialog small · medium · large width 320 / 480 / 640px
Icon, Spinner, Avatar numbers, in px; Icon also takes inherit the icon or avatar size
Small Medium Large
<tk-button size="small">Small</tk-button>
<tk-button>Medium</tk-button>
<tk-button size="large">Large</tk-button>

size="small" on a field renders as medium and logs a console warning. Tables set spacing with density (comfortable · compact), not size.

Events

  • Value changes fire change (and input while the value is moving, as on Slider), like native form controls. Dialog, Confirm dialog and Sheet fire the native close and cancel.
  • Every other event starts with tk-, bubbles, and crosses shadow DOM, so you can listen on any ancestor. change bubbles but, like the native event, stays inside the shadow root it was fired in.
  • Some events fire before the change and can be canceled. Call preventDefault() to stop it: tk-dismiss, tk-toggle, tk-sort, tk-commit. The component's page says which events can be canceled.
  • detail is a plain object that holds only what you can't read from the element.
banner.addEventListener('tk-dismiss', (event) => {
  event.preventDefault(); // keep the banner; remove it yourself later
});

Slots

The default slot holds the component's own content: its label or body. Named slots reuse the same few names:

Slot What goes in it On
icon-start, icon-end an icon before or after the label Button
prefix, suffix an icon or unit inside a field Input, Number input
icon one icon leading a message or item Banner, Section message, Menu item, Sidebar nav item
leading, trailing content at the start or end of a row Tag (leading); Menu item, Sidebar nav item (trailing)
title, actions a heading and a row of buttons Section message, Empty state; Banner (actions)
action exactly one button Toast, Split button
footer the bottom region Dialog, Sheet, Sidebar
trigger the element that opens it Menu, Popover, Collapsible
Add member USD
<tk-button><tk-icon slot="icon-start" name="plus"></tk-icon>Add member</tk-button>
<tk-input aria-label="Price"><span slot="suffix">USD</span></tk-input>

Overlays

  • Dialog, Confirm dialog, Sheet are modal. Esc closes them unless persistent is set, and focus returns to the element that opened them. Each page says when a backdrop click closes it.
  • Menus, popovers, and the panels of Select, Combobox and the pickers are not modal. A click outside or Esc closes them.
  • Tooltip shows on hover and focus. Toast is announced without taking focus.

Styling hooks

  • ::part(name) reaches the parts each component page lists under API.
  • Custom properties named --tk-<component>-<what> are public, such as --tk-popover-max-width or --tk-sidebar-width, and each is listed on its page.
  • Anything starting with --_ is private and can change without notice.