Elements & Styles
TIP
This page describes today's surface. Closing the gap with Vue and DOM web standards is an ongoing direction for the project.
Elements are just boxes
Every tag other than "input" (<div>, <span>, <button>, anything) renders as a generic styled container. Elements carry no default styles, so a <button> starts as the same plain box as a <div> and :style sets everything. "input" is a text field, described below.
button
A button is a box that also takes keyboard focus.
- Its
tabindexis 0 by default, so it takes focus on its own. An explicittabindexoverrides that. EnterandSpaceclick it from the keyboard.
<template>
<button
:style="{ width: 80, height: 32, backgroundColor: '#2266ff' }"
:disabled="saving"
@click="save"
>
Save
</button>
</template>input
An input is a one-line text field.
- Every
typerenders as a text field, sotype="password"shows the characters. - It has no default size. Without a height in
:styleit is one line of itsfontSizetall, and its width comes from:style. The text line sits at the top of the box. - The caret is a 1px bar in the text color and does not blink. The selection is a fixed light blue, and the
placeholdershows in the text color at half opacity. - Word-wise moves and deletes, Cmd+Left, Cmd+Right, Cmd+Backspace, Ctrl+A, Ctrl+E and Option with an arrow on macOS, undo, and a double-click word selection are unsupported.
selectionStart,selectionEnd,selectionDirection,setSelectionRange(),select(),defaultValue,maxLengthandsizeare missing.
style
A style element applies its rules to every element of the app and is never drawn. The elements of a <style> block and of an imported stylesheet are children of the mount container. You can also render one with h("style", css) or <component is="style">.
- The declarations take the keys and values of
:style. The host drops any other declaration, see Why does a rule of my stylesheet have no effect?. !importantis read as a normal declaration, so an inline value still wins.@mediaand the other at-rules, including an@importthat the build did not resolve, have no effect.- Native CSS nesting, custom properties,
var()andurl()values have no effect. v-bind()in a<style>block fails the build.- The
media,typeanddisabledattributes are ignored. - The host draws no focus indicator and no look for
:hoveror:active. :hoverand:activechange only while the app has an event listener, a focusable element or a rule that names them.:focus-visibleand the other interactive pseudo-classes never match.
Accessibility
role and the aria-* attributes reach no assistive technology. ariaNotify() is missing.
Recognized style keys
:style takes an object or a string. Only the keys below are read.
An object gives each key its own accepted value shapes. A value of the wrong shape sets the property to its default, even when the key held a valid value before. An unrecognized key has no effect. Removing a key, or setting it to null or undefined, restores that property to its default.
The host prints a warning line on stderr the first time an element sets an unrecognized key or a value of a shape the host does not support. An empty string '' on a known key prints no warning.
A string is a list of CSS declarations, such as "gap: 8px; color: #f00". Its property names are the keys of the table in kebab-case, such as flex-direction, and its values are the values of the table. The host drops any other declaration. A string replaces every property set before. null or undefined clears every property set before.
A px size is a number or a string such as "10px". A string that reads as zero, such as "0" or "0.0", also works. Other units are not supported. opacity, flexGrow and flexShrink also take a decimal string such as "0.5". opacity also takes a percentage such as "50%". A key that starts with - is unknown.
| Key | Value | Notes |
|---|---|---|
display | "flex" | "block" | "grid" | "none" | |
flexDirection | "row" | "column" | "row-reverse" | "column-reverse" | |
justifyContent | "start" | "end" | "flex-start" | "flex-end" | "center" | "stretch" | main-axis alignment |
alignItems | "start" | "end" | "flex-start" | "flex-end" | "center" | "stretch" | cross-axis alignment |
gap | px size (>= 0) | applied on both axes |
width | px size (>= 0) | "auto" | |
height | px size (>= 0) | "auto" | |
borderWidth | px size (>= 0) | applied to all four sides |
backgroundColor | color (below) | fill |
borderColor | color (below) | |
borderRadius | px size (>= 0) | applied to all four corners |
color | color (below) | cascades to descendant text leaves |
fontSize | px size (>= 0) | cascades to descendant text leaves; a size above 2048px applies as 2048px |
overflow / overflowX / overflowY | "visible" | "hidden" | "clip" | "scroll" | "auto"; overflow also takes two of them, x then y | "hidden" clips and script can scroll it; "scroll" and "auto" also scroll with the wheel; overflowX/overflowY win over overflow |
padding / paddingX / paddingY / paddingTop / paddingRight / paddingBottom / paddingLeft | px size (>= 0) | a negative, NaN or infinite number is ignored |
margin / marginX / marginY / marginTop / marginRight / marginBottom / marginLeft | px size (negative allowed) | "auto" | |
flexGrow / flexShrink | number or decimal string (>= 0) | |
opacity | number, decimal string or percentage (0 to 1, 0% to 100%) | clamped; NaN and infinity are ignored; applies to descendants too |
minWidth / minHeight / maxWidth / maxHeight | px size (>= 0) | "auto" | "auto" is the default limit: none for the max keys, the content size for a flex item's min keys |
A length above 33554428px and a flex factor above 1e18 apply at that value and read back as it, as a text (1e999px, 99999999px, 1e19) or as a number: 33554428px for a length, -33554428px for a margin, 1000000000000000000 for flexGrow and flexShrink. An opacity text beyond the largest number reads back 3.4028234663852886e+38, and a JS number above it reads back as written.
Content taller than the window is cut off at the window edge; see Why doesn't my content scroll.
For padding and margin, a side key beats its axis key (paddingX for left and right, paddingY for top and bottom), and an axis key beats the shorthand. A value of the wrong shape counts as unset and the next key applies.
"auto" draws its scrollbar over the content and reserves no width. The scrollbar has no arrow buttons, and a click on the track does not scroll. An overlay scrollbar hides without a fade. scrollbarWidth and scrollbarColor are not supported, and their keys are ignored.
position and zIndex are not supported, and their keys are ignored.
Color format
backgroundColor, borderColor and color each take a numeric 0xRRGGBB literal, e.g. 0xff0000, or a string of the CSS <color> type.
A number must lie from 0 to 0xffffff. Other notations, such as color names, hsl() and currentcolor, are not supported. rgb() does not take none, calc() or var(), and percentage channels need whitespace between them.
Template refs
A template ref is an element handle. Its members behave as described for Element and HTMLElement, with the differences below.
A box read returns the box of the last drawn frame, so
onMountedreads zeros.offsetParentis the parent element, ornullwhen the node or its parent has no box.A scroll write is stored at once. A read clamps it to the maximum of the last drawn frame, so a write beyond that maximum, or one made before the first draw, reads smaller until the next frame.
scrollWidthandscrollHeightof a"visible"or"clip"element equal its client size.The scroll range of a
"hidden","scroll"or"auto"element leaves out the end margins of its children and content that overflows a child.Every scroll applies at once, whatever
behaviorsays.focus()andscrollIntoView()on a node that has no box yet scroll when the next frame draws it.Only
pointerId1 is accepted bysetPointerCapture(),releasePointerCapture()andhasPointerCapture().A node of a removed subtree, of one never inserted, of a fragment or of a copy made by
cloneNode()is freed with that subtree once the script holds no reference to the top of the subtree. Its links then readnull.before(),after(),replaceWith()andremove()on it do nothing. Inserting it, or using it as a parent, throws aTypeError, and using it as the anchor throws aNotFoundError.append(),prepend(),before(),after(),replaceWith()andreplaceChildren()change nothing when they throw, also when they get several nodes.The mount container can be collected while it sits in
documentand the script holds no reference to it. A later read returns a new object, without the properties the script set on the old one.One run of the app can create 2^32 - 3 nodes in total. A template counts as two, and a removed node still counts. After that, every call that creates a node throws a
TypeError.A node that a template removes (for example with
v-if) drops its listeners for good. Appending it again does not restore them.removeChild(),replaceChild(),remove(),replaceWith()andreplaceChildren()keep the listeners of the nodes they remove.classListhas no index properties.classList[0]isundefined, and no index shows up when you list the keys of the object or serialize it to JSON. Read a token withitem()or iterate over the list.These iteration functions of
classListare the host's own functions. They differ from theArray.prototypefunctions. Their iterators have a different prototype from the one of[].values(). The tag of such an iterator readsArray Iterator.values()keys()entries()forEach()[Symbol.iterator]
The
classNameof an SVG element is a string, and assigning to it writes theclassattribute.These constructors throw a
TypeError. Create nodes with the methods ofdocument.new EventTarget()new Text()new Comment()new DocumentFragment()
An element of the HTML namespace is an instance of
HTMLElementwhatever its tag. The interfaces of single tags are missing, for example:HTMLInputElementHTMLUnknownElement
An element of the SVG or MathML namespace is an instance of
Element. These interfaces are missing:SVGElementMathMLElement
documentand a fragment have nogetElementById().The only element child of
documentis the mount container. These members give it:document.firstElementChilddocument.lastElementChilddocument.children[0]
The nodes of a copy of
document, and the nodes its creation methods make, readdocumentas theirownerDocument.The methods below store U+FFFD for each half of a surrogate pair they split:
splitText()substringData(),insertData(),deleteData(),replaceData()
A string with a lone surrogate that a member writes into the document, as text data or as an attribute value, throws a
TypeError.The objects these members return are not instances of the standard classes, so
instanceofagainst the class name isfalse:children(HTMLCollection)childNodes(NodeList)attributes(NamedNodeMap)- the items of
attributes(Attr) querySelectorAll()(NodeList)
The pseudo-class rules below hold for these methods:
closest()matches()querySelector()querySelectorAll()
They accept
:focus-visibleand the other interactive and form-state pseudo-classes and never match them, so:not(:focus-visible)matches every element.:lang()and:state()never match.:dir(ltr)matches every element and any other:dir()value never matches.:disabledand:enabledapply to HTMLbuttonandinputonly.These members of
attributesare missing:setNamedItem()andremoveNamedItem()getNamedItemNS(),setNamedItemNS()andremoveNamedItemNS()
An
Attrhas noNodemembers.Attributes have no namespace.
xlink:hrefis an attribute namedxlink:href.Attr.namespaceURIandAttr.prefixreadnull, and theNSattribute methods are missing.An
<svg>that a Vue template creates is an element of the HTML namespace:namespaceURIreads the HTML namespace,tagNamereadsSVGand attribute names such asviewBoxare lower case.
style and dataset
stylereads and writes the keys of Recognized style keys and these host-only keys:textColortextSizecornerRadius
- A name that
setProperty()does not know, and a value the host cannot read such as a number without a unit, print a warning and change nothing. !importantis dropped.getPropertyPriority()returns an empty string.- A shorthand key is stored as written. Reading a longhand does not take the shorthand's value, and a longhand wins over its shorthand whatever the order.
stylehas no indexed access and is not iterable. These members read the declarations:item()length
getAttribute("style")returns the declarations the host applied, in serialized form, also before any write. Declarations the host dropped are not in it. An attribute selector andisEqualNode()read that text. The attribute is created by the first declaration written, soa,style.width,blistsa, style, b.
Parsed HTML
- A
styleattribute in parsed markup applies the declarations that:styleknows and warns about the others. The attribute reads back the applied declarations. - An
on*attribute stays a plain attribute and registers no listener.
Vue features that don't work yet
A few common Vue features depend on DOM concepts this renderer doesn't have, and using them fails the build:
v-showand<Transition>fail to build with a RollupMISSING_EXPORTerror ("vShow"/"Transition"is not exported by the runtime). So doesv-modelon a<select>, a checkbox, a radio button or an<input>with a bound:type("vModelSelect","vModelCheckbox","vModelRadio","vModelDynamic").v-modelon a<textarea>builds, and the<textarea>stays a plain box. On any other elementv-modelfails at the template-compiler stage.- No
fetch:fetchisn't provided as a global by the JS runtime Incarnative.js embeds.
Event modifiers such as .stop, .once and @keydown.enter are documented in Events: Event modifiers.
Bootstrapping: src/main.ts
Incarnative.js wraps src/App.vue in a synthesized entry equivalent to the one below. Write src/main.ts yourself for full control over bootstrapping. The entry setting lists the files Incarnative.js looks for.
import { createIncaApp } from "incajs/vue";
import App from "./App.vue";
createIncaApp(App).mount();createIncaApp(rootComponent, rootProps?) creates a Vue App whose mount() targets the host's mount container when called with no argument; otherwise it behaves exactly like Vue's own App (use, mixin, component, directive, unmount, ...).