hypereffect

Components

hypereffect defines eighteen components. Renderers implement all of them. Servers cannot add more.

Containers

column

Arranges children vertically. The root of the session behaves as a column with default attributes. 

element {"id":"col","type":"column"}
element {"id":"a","type":"text","parent":"col","text":"Lorem ipsum"}
element {"id":"b","type":"text","parent":"col","text":"Dolor sit amet"}
Attribute Type Default Notes
id string — Required. Unique within the session. Literal.
type string — Required. Always "column". Literal.
parent string root Id of the containing element. Literal. Must be a column, row, card, list, tab or dialog.
before string last Id of a sibling to insert before. Omitted means append (new elements) or keep the current position (updates). Literal.
visible bool true expression When false the element and its descendants are not shown and take no space.
gap enum medium expression none · small · medium · large.
align enum stretch expression start · center · end · stretch. Horizontal alignment of children.

row

Arranges children horizontally. Renderers on narrow surfaces may wrap a row even when wrap is false, rather than overflow. 

element {"id":"row","type":"row"}
element {"id":"a","type":"text","parent":"row","text":"Lorem ipsum"}
element {"id":"b","type":"text","parent":"row","text":"Dolor sit amet"}
Attribute Type Default Notes
id string — Required. Unique within the session. Literal.
type string — Required. Always "row". Literal.
parent string root Id of the containing element. Literal. Must be a column, row, card, list, tab or dialog.
before string last Id of a sibling to insert before. Omitted means append (new elements) or keep the current position (updates). Literal.
visible bool true expression When false the element and its descendants are not shown and take no space.
gap enum small expression none · small · medium · large.
align enum center expression start · center · end · stretch. Vertical alignment of children.
justify enum start expression start · center · end · between.
wrap bool false expression

card

A visually grouped region, laid out as a column. Typically drawn with a border or a distinct background. 

element {"id":"card","type":"card","title":"Lorem ipsum"}
element {"id":"a","type":"text","parent":"card","text":"Lorem ipsum"}
element {"id":"b","type":"text","parent":"card","text":"Dolor sit amet"}
Attribute Type Default Notes
id string — Required. Unique within the session. Literal.
type string — Required. Always "card". Literal.
parent string root Id of the containing element. Literal. Must be a column, row, card, list, tab or dialog.
before string last Id of a sibling to insert before. Omitted means append (new elements) or keep the current position (updates). Literal.
visible bool true expression When false the element and its descendants are not shown and take no space.
title string none expression Shown as a heading for the group.
gap enum medium expression none · small · medium · large.

list

A vertical sequence of items with separators. Each child is one item. Renderers may virtualise long lists. 

element {"id":"list","type":"list"}
element {"id":"a","type":"text","parent":"list","text":"Lorem ipsum"}
element {"id":"b","type":"text","parent":"list","text":"Dolor sit amet"}
Attribute Type Default Notes
id string — Required. Unique within the session. Literal.
type string — Required. Always "list". Literal.
parent string root Id of the containing element. Literal. Must be a column, row, card, list, tab or dialog.
before string last Id of a sibling to insert before. Omitted means append (new elements) or keep the current position (updates). Literal.
visible bool true expression When false the element and its descendants are not shown and take no space.
empty string none expression Text shown when the list has no visible children.

tabs

Shows one of its tab children at a time, with a control to switch between them. Switching is local and does not contact the server unless onChange has an action. 

element {"id":"tabs","type":"tabs"}
element {"id":"a","type":"tab","parent":"tabs","label":"Lorem"}
element {"id":"b","type":"tab","parent":"tabs","label":"Ipsum"}
Attribute Type Default Notes
id string — Required. Unique within the session. Literal.
type string — Required. Always "tabs". Literal.
parent string root Id of the containing element. Literal. Must be a column, row, card, list, tab or dialog.
before string last Id of a sibling to insert before. Omitted means append (new elements) or keep the current position (updates). Literal.
visible bool true expression When false the element and its descendants are not shown and take no space.
bind path none Signal holding the id of the selected tab. If missing or not the id of a visible child, the first visible tab is shown. Without bind the selection is renderer state. Literal.
onChange handler none Runs after the selection changes. Literal.

tab

One page of a tabs element, laid out as a column. Its parent must be a tabs. 

element {"id":"tabs","type":"tabs"}
element {"id":"tab","type":"tab","parent":"tabs","label":"Lorem"}
element {"id":"a","type":"text","parent":"tab","text":"Lorem ipsum"}
element {"id":"b","type":"text","parent":"tab","text":"Dolor sit amet"}
Attribute Type Default Notes
id string — Required. Unique within the session. Literal.
type string — Required. Always "tab". Literal.
parent string — Required. Must be a tabs. Literal.
before string last Id of a sibling to insert before. Omitted means append (new elements) or keep the current position (updates). Literal.
visible bool true expression When false the element and its descendants are not shown and take no space.
label string the id expression Shown in the tab control.
gap enum medium expression none · small · medium · large.

dialog

A modal surface shown above the rest of the interface, laid out as a column. A dialog cannot have a parent. While any dialog is open, the renderer should prevent interaction with elements outside it. If several are open, the most recently opened is on top. 

element {"id":"dialog","type":"dialog","title":"Lorem ipsum"}
element {"id":"a","type":"text","parent":"dialog","text":"Lorem ipsum"}
element {"id":"b","type":"text","parent":"dialog","text":"Dolor sit amet"}
Attribute Type Default Notes
id string — Required. Unique within the session. Literal.
type string — Required. Always "dialog". Literal.
parent string — Not allowed: a dialog is always at the root.
before string last Id of a sibling to insert before. Omitted means append (new elements) or keep the current position (updates). Literal.
visible bool true expression When false the element and its descendants are not shown and take no space.
open bool true expression
title string none expression
onDismiss handler none Runs when the user asks to close the dialog (Escape, back gesture, close button). If absent, the dialog cannot be dismissed by the user. The renderer does not close the dialog itself; the handler must change whatever open depends on, or the server must. Literal. 
element {"id":"confirm","type":"dialog","title":"Delete project?",
         "open":{"cel":"has(s._confirm) && s._confirm"},
         "onDismiss":{"patch":{"_confirm":false}}}

Content

text

element {"id":"text","type":"text","text":"Lorem ipsum dolor sit amet"}
Attribute Type Default Notes
id string — Required. Unique within the session. Literal.
type string — Required. Always "text". Literal.
parent string root Id of the containing element. Literal. Must be a column, row, card, list, tab or dialog.
before string last Id of a sibling to insert before. Omitted means append (new elements) or keep the current position (updates). Literal.
visible bool true expression When false the element and its descendants are not shown and take no space.
text string "" expression Plain text. Line breaks are preserved. No markup.
variant enum body expression h1 · h2 · h3 · body · caption · code

Heading variants should be exposed as headings to assistive technology. code is monospaced where the platform allows. caption is secondary, lower-emphasis text.

notice

A message that draws attention: a confirmation, a warning, an error.

element {"id":"notice","type":"notice","title":"Lorem ipsum","text":"Dolor sit amet"}
Attribute Type Default Notes
id string — Required. Unique within the session. Literal.
type string — Required. Always "notice". Literal.
parent string root Id of the containing element. Literal. Must be a column, row, card, list, tab or dialog.
before string last Id of a sibling to insert before. Omitted means append (new elements) or keep the current position (updates). Literal.
visible bool true expression When false the element and its descendants are not shown and take no space.
title string none expression
text string "" expression
variant enum info expression info · success · warning · failure

Renderers should announce a warning or failure notice to assistive technology when it appears or its text changes.

badge

A short status label, usually shown inline in a row.

element {"id":"badge","type":"badge","text":"lorem"}
Attribute Type Default Notes
id string — Required. Unique within the session. Literal.
type string — Required. Always "badge". Literal.
parent string root Id of the containing element. Literal. Must be a column, row, card, list, tab or dialog.
before string last Id of a sibling to insert before. Omitted means append (new elements) or keep the current position (updates). Literal.
visible bool true expression When false the element and its descendants are not shown and take no space.
text string "" expression
variant enum neutral expression neutral · info · success · warning · failure

image

element {"id":"image","type":"image","variant":"avatar","alt":"Lorem","src":"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Crect width='64' height='64' fill='%236a46e0'/%3E%3Ccircle cx='32' cy='25' r='12' fill='%23fff'/%3E%3Crect x='12' y='42' width='40' height='26' rx='13' fill='%23fff'/%3E%3C/svg%3E"}
Attribute Type Default Notes
id string — Required. Unique within the session. Literal.
type string — Required. Always "image". Literal.
parent string root Id of the containing element. Literal. Must be a column, row, card, list, tab or dialog.
before string last Id of a sibling to insert before. Omitted means append (new elements) or keep the current position (updates). Literal.
visible bool true expression When false the element and its descendants are not shown and take no space.
src string "" expression A URI. Which schemes are fetched is up to the renderer and its host; data: should be supported.
alt string "" expression Shown or announced when the image cannot be displayed. Renderers that cannot show images (a terminal) show the alt text.
variant enum inline expression inline · thumbnail · avatar · full

divider

A separator line along the main axis of its parent.

element {"id":"divider","type":"divider"}
Attribute Type Default Notes
id string — Required. Unique within the session. Literal.
type string — Required. Always "divider". Literal.
parent string root Id of the containing element. Literal. Must be a column, row, card, list, tab or dialog.
before string last Id of a sibling to insert before. Omitted means append (new elements) or keep the current position (updates). Literal.
visible bool true expression When false the element and its descendants are not shown and take no space.

progress

element {"id":"progress","type":"progress","label":"Lorem ipsum","value":0.6}
Attribute Type Default Notes
id string — Required. Unique within the session. Literal.
type string — Required. Always "progress". Literal.
parent string root Id of the containing element. Literal. Must be a column, row, card, list, tab or dialog.
before string last Id of a sibling to insert before. Omitted means append (new elements) or keep the current position (updates). Literal.
visible bool true expression When false the element and its descendants are not shown and take no space.
value number or null null expression Between 0 and 1. Null means indeterminate. Values outside the range are clamped.
label string none expression
variant enum bar expression bar · spinner

Controls

button

element {"id":"button","type":"button","label":"Lorem","onPress":{"action":"lorem"}}
Attribute Type Default Notes
id string — Required. Unique within the session. Literal.
type string — Required. Always "button". Literal.
parent string root Id of the containing element. Literal. Must be a column, row, card, list, tab or dialog.
before string last Id of a sibling to insert before. Omitted means append (new elements) or keep the current position (updates). Literal.
visible bool true expression When false the element and its descendants are not shown and take no space.
disabled bool false expression Shown but cannot be operated, and does not run handlers.
label string "" expression
variant enum secondary expression primary · secondary · plain · success · failure. Use failure for destructive actions.
onPress handler none Literal.

input

A text field. The value is stored in the bound signal: a string, or a number for the number variant (null when the field is empty or does not parse). 

element {"id":"input","type":"input","label":"Lorem","placeholder":"Ipsum"}
Attribute Type Default Notes
id string — Required. Unique within the session. Literal.
type string — Required. Always "input". Literal.
parent string root Id of the containing element. Literal. Must be a column, row, card, list, tab or dialog.
before string last Id of a sibling to insert before. Omitted means append (new elements) or keep the current position (updates). Literal.
visible bool true expression When false the element and its descendants are not shown and take no space.
disabled bool false expression Shown but cannot be operated, and does not run handlers.
bind path none Without bind the field's value is not observable. Literal.
label string none expression
placeholder string none expression
error string "" expression A validation message. A non-empty value marks the field invalid.
variant enum text expression text · multiline · password · number · email
onChange handler none Runs when the user has finished an edit: on losing focus, or after a short idle period chosen by the renderer. Not on every keystroke. Literal.
onSubmit handler none Runs when the user confirms (Enter in a single-line field). Not available for multiline. Literal. 
element {"id":"email","type":"input","parent":"form","label":"Email","variant":"email",
         "bind":"form.email","error":{"cel":"has(s.errors.email) ? s.errors.email : ''"}}

checkbox

A boolean control. The bound signal is true or false.

element {"id":"checkbox","type":"checkbox","label":"Lorem ipsum"}
Attribute Type Default Notes
id string — Required. Unique within the session. Literal.
type string — Required. Always "checkbox". Literal.
parent string root Id of the containing element. Literal. Must be a column, row, card, list, tab or dialog.
before string last Id of a sibling to insert before. Omitted means append (new elements) or keep the current position (updates). Literal.
visible bool true expression When false the element and its descendants are not shown and take no space.
disabled bool false expression Shown but cannot be operated, and does not run handlers.
bind path none Literal.
label string "" expression
variant enum checkbox expression checkbox · switch
onChange handler none Runs after each change. Literal.

select

A choice of one value from a list. The bound signal holds the value of the selected option, or null. 

element {"id":"select","type":"select","label":"Lorem","options":[{"value":"a","label":"Ipsum"},{"value":"b","label":"Dolor"}]}
Attribute Type Default Notes
id string — Required. Unique within the session. Literal.
type string — Required. Always "select". Literal.
parent string root Id of the containing element. Literal. Must be a column, row, card, list, tab or dialog.
before string last Id of a sibling to insert before. Omitted means append (new elements) or keep the current position (updates). Literal.
visible bool true expression When false the element and its descendants are not shown and take no space.
disabled bool false expression Shown but cannot be operated, and does not run handlers.
bind path none Literal.
label string none expression
options list [] expression Objects with value (string) and label (string). Can be an expression, e.g. derived from a signal.
variant enum dropdown expression dropdown · radio · segmented
onChange handler none Runs after each change. Literal.

slider

A number within a range. The bound signal holds the number.

element {"id":"slider","type":"slider","label":"Lorem"}
Attribute Type Default Notes
id string — Required. Unique within the session. Literal.
type string — Required. Always "slider". Literal.
parent string root Id of the containing element. Literal. Must be a column, row, card, list, tab or dialog.
before string last Id of a sibling to insert before. Omitted means append (new elements) or keep the current position (updates). Literal.
visible bool true expression When false the element and its descendants are not shown and take no space.
disabled bool false expression Shown but cannot be operated, and does not run handlers.
bind path none Literal.
label string none expression
min number 0 expression
max number 100 expression
step number 1 expression
onChange handler none Runs when the user releases the slider, not continuously while dragging. Literal.