ConstThe core function for building reactive user interfaces in Aberdeen. It creates and inserts new DOM elements and sets attributes/properties/event listeners on DOM elements. It does so in a reactive way, meaning that changes will be (mostly) undone when the current scope is destroyed or will be re-execute.
Any number of arguments can be given. How they're interpreted depends on their types:
Strings can be used to create and insert new elements, set classnames for the current element, and add text to the current element.
The format of a string is: (tag | . class | key[=:]val | key[=:]"val containing spaces")* ('#' text | key[=:])?
So a string may consist of any number of...
tag elements, like h1 or div. These elements are created, added to the current element, and become the new current element for the rest of this A function execution.
CSS classes prefixed by . characters. These classes will be added to the current element. Optionally, CSS classes can be appended to a tag without a space. So both div.myclass and div .myclass are valid and do the same thing.
Property key/value pairs, like type=password, placeholder="Your name" or data-id=123. When the value contains spaces, it needs to be quoted with either "double quotes", 'single quotes' or backticks. Quotes within quoted values cannot be escaped (see the next rule for a solution). Key/value pairs will be handled according to Property rules below, but with the caveat that values can only be strings.
CSS key/value pairs using two syntaxes:
key:value (no space after colon): The value ends at the next whitespace. Example: m:$3 bg:red r:8pxkey: value; (space after colon): The value continues until a semicolon. Example: box-shadow: 2px 0 6px black; transition: all 0.3s ease;Both forms support CSS shortcuts (see below). You can mix them: m:$3 box-shadow: 0 2px 4px rgba(0,0,0,0.2); bg:$cardBg
The elements must be separated by spaces, except before a .cssClass if it is preceded by either tag or another CSS class.
And a string may end in...
TextNode to the current element. The text ranges til the end of the string, and may contain any characters, including spaces and quotes.A('button text="Click me" click=', () => alert('Clicked!')) or A('input.value=', someUserData, "placeholder=", "Type your stuff"). In case the value is a proxied object, its .value property will be applied reactively without needing to rerender the parent scope.A('div margin-top:', someValueInPx). In case the value is a proxied object, its .value property will be applied reactively without needing to rerender the parent scope.When a function (without arguments nor a return value) is passed in, it will be reactively executed in its own observer scope, preserving the current element. So any A() invocations within this function will add child elements to or set properties on that element. If the function reads observable data, and that data is changed later on, the function we re-execute (after side effects, such as DOM modifications through A, have been cleaned - see also clean).
When an object is passed in, its key-value pairs are used to modify the current element according to the Property rules below, unless the key starts with a $ character, in which case that character is stripped of and the key/value pair is treated as a CSS property, subject to the CSS shortcuts below. In case a value is a proxied object, its .value property will be applied reactively without needing to rerender the parent scope. In most cases, the string notation (key= and key:) is preferred over this object notation, for readability.
When a DOM Node (Element or TextNode) is passed in, it is added as a child to the current element. If the Node is an Element, it becomes the new current element for the rest of this A function execution.
A('input placeholder=Name') results in <input placeholder="Name">.function it is set as an event listener for the event with the name given by the key. For example: A('button text=Press! click=', () => alert('Clicked!'))`. The event listener will be removed when the current scope is destroyed."value" or "selectedIndex", it is set on the current element as a DOM property instead of an HTML attribute. For example A('checked=', true) would do el.checked = true for the current element.. character, its either added to or removed from the current element as a CSS class, based on the truthiness of the value. So A('.hidden=', isHidden) would toggle the hidden CSS class. This only works if the = is the last character of the string, and the next argument is the value. Its common for the value to be a proxied object, in which case its .value is reactively applied without needing to rerender the parent scope."create", the value will be added as a CSS class to the current element immediately, and then removed right after the browser has finished doing a layout pass. This behavior only triggers when the scope setting the create is the top-level scope being (re-)run. This allows for creation transitions, without triggering the transitions for deeply nested elements being drawn as part of a larger component. The string may also contain multiple dot-separated CSS classes, such as .fade.grow. The initial dot is optional. Alternatively, to allow for more complex transitions, the value may be a function that receives the HTMLElement being created as its only argument. It is only called if this is the top-level element being created in this scope run. See transitions.ts in the Aberdeen source code for some examples."destroy" the value will be used to apply a CSS transition if the current element is later on removed from the DOM and is the top-level element to be removed. This happens as follows: actual removal from the DOM is delayed by 2 seconds, and in the mean-time the value string is added as a CSS class to the element, allowing for a deletion transition. The string may also contain multiple dot-separated CSS classes, such as .fade.shrink. The initial dot is optional. Alternatively, to allow for more complex transitions, the value may be a function that receives the HTMLElement to be removed from the DOM as its only argument. This function may perform any transitions and is then itself responsible for eventually removing the element from the DOM. See transitions.ts in the Aberdeen source code for some examples."bind" a two-way binding between the .value property of the given proxied object, and the current input element (<input>, <select> or <textarea>) is created. This is often used together with {@link ref}, in order to use properties other than .value."text", the value will be appended as a TextNode to the current element. The same can also be done with the # syntax in string arguments, though text= allows additional properties to come after in the same string: A('button text=Hello click=', alert)."html", the value will be added as HTML to the current element. This should only be used in exceptional situations. Beware of XSS! Never use this with untrusted user data."rich", the value is parsed as simple markdown-like syntax and rendered as inline elements. Supports *italic*, **bold**, `code`, and [link text](/path). All text content is safely escaped, making it suitable for user data (though links should be validated if untrusted). Example: A('p rich="Click *here* for **more** info").For conciseness, Aberdeen supports some CSS shortcuts when setting CSS properties.
| Shortcut | Expands to |
|---|---|
m, mt, mb, ml, mr |
margin, margin-top, margin-bottom, margin-left, margin-right |
mv, mh |
Vertical (top+bottom) or horizontal (left+right) margins |
p, pt, pb, pl, pr |
padding, padding-top, padding-bottom, padding-left, padding-right |
pv, ph |
Vertical or horizontal padding |
w, h |
width, height |
bg |
background |
fg |
color |
r |
border-radius |
Also, when the value is a string starting with $, it is treated as a reference to a CSS variable, expanding to var(--variableName). For numeric variable names (which can't be used directly as CSS custom property names), Aberdeen prefixes them with m, so $3 expands to var(--m3). This is primarily intended for use with setSpacingCssVars, which initializes spacing variables named 0 through 12 with an exponential spacing scale.
The most inner DOM element that was created (not counting text nodes nor elements created by content functions), or the current element if no new element was created. You should normally not need to use the return value - use this function's DOM manipulation abilities instead. One valid use case is when integrating with non-Aberdeen code that requires a reference to a DOM element.
A('button.secondary.outline text=Submit color:red disabled=', false, 'click=', () => console.log('Clicked!'));
We want to set disabled as a property instead of an attribute, so we must use the key= syntax in order to provide
false as a boolean instead of a string.
let inputElement: Element = A('label text="Click me" input type=checkbox');
// You should usually not touch raw DOM elements, unless when integrating
// with non-Aberdeen code.
console.log('DOM element:', inputElement);
const state = A.proxy({ count: 0 });
A('div', () => { // Outer element
// This scope re-renders when state.count changes
A(`p#Count is ${state.count}`);
A('button text=Increment click=', () => state.count++);
});
const user = A.proxy({ name: '' });
A('input placeholder=Name bind=', A.ref(user, 'name'));
A('h3', () => { // Reactive scope
A(`#Hello ${user.name || 'stranger'}`);
});
const show = A.proxy(false);
A('button click=', () => show.value = !show.value, () => A(show.value ? '#Hide' : '#Show'));
A(() => { // Reactive scope
if (show.value) {
A('p#Details are visible!');
}
});
const myColor = A.proxy('red');
A('p text="The color is " text=', myColor, 'click=', () => myColor.value = 'yellow')
// Clicking the text will cause it to change color without recreating the <p> itself
This is often used together with ref, in order to use properties other than .value.
Registers a cleanup function to be executed just before the current reactive scope is destroyed or redraws.
This is useful for releasing resources, removing manual event listeners, or cleaning up side effects associated with the scope. Cleaners are run in reverse order of registration.
Scopes are created by functions like derive, mount, A (when given a render function), and internally by constructs like onEach.
Clone an (optionally proxied) object or array.
Recursively copies properties or array items from src to dst.
It's designed to work efficiently with reactive proxies created by proxy.
dst with the same constructor as the corresponding object in src, copy
will recursively copy properties into the existing dst object instead of replacing it.
This minimizes change notifications for reactive (proxied) destinations.copy uses Aberdeen internals
to speed things up (compared to a non-Aberdeen-aware deep copy).Reactively counts the number of properties in an objects.
A reactive object containing CSS variable definitions.
Any property you assign to cssVars becomes available as a CSS custom property throughout your application.
Use setSpacingCssVars to optionally initialize cssVars[1] through cssVars[12] with an exponential spacing scale.
When you reference a CSS variable in Aberdeen using the $ prefix (e.g., $primary), it automatically resolves to var(--primary).
For numeric keys (which can't be used directly as CSS custom property names), Aberdeen prefixes them with m (e.g., $3 becomes var(--m3)).
When you add the first property to cssVars, Aberdeen automatically creates a reactive <style> tag in <head>
containing the :root CSS custom property declarations. The style tag is automatically removed if cssVars becomes empty.
Creates a reactive scope that automatically re-executes the provided function whenever any proxied data (created by proxy) read during its last execution changes, storing its return value in an observable.
Updates are batched and run asynchronously shortly after the changes occur. Use clean to register cleanup logic for the scope. Use peek or unproxy within the function to read proxied data without subscribing to it.
Make the create and destroy special properties no-ops.
This is useful from within automated testing environments, where the transitioning new and lingering old elements may make writing reliable selectors difficult.
As this is only intended for testing, there's no way to re-enable the special properties once disabled.
Renders a live, recursive dump of a proxied data structure (or any value) into the DOM at the current A insertion point.
Uses <ul> and <li> elements to display object properties and array items.
Updates reactively if the dumped data changes. Primarily intended for debugging purposes.
Inserts CSS rules into the document, scoping them with a unique class name.
The style parameter can be either:
& representing the root class)
and values are concise style strings or nested objects. When the key does not contain &,
it is treated as a descendant selector. So {p: "color:red"} becomes ".AbdStlX p { color: red; }" with AbdStlX being the generated class name.Concise style strings use two syntaxes (same as inline CSS in A):
key:value (no space after colon): The value ends at the next whitespace.
Example: 'm:$3 bg:red r:8px'key: value; (space after colon): The value continues until a semicolon.
Example: 'box-shadow: 2px 0 6px black; transition: all 0.3s ease;'Both forms can be mixed: 'm:$3 box-shadow: 0 2px 4px rgba(0,0,0,0.2); bg:$cardBg'
Supports the same CSS shortcuts as A and CSS variable references with $ (e.g., $primary, $3).
The unique class name prefix used for scoping (e.g., .AbdStl1).
Use this prefix with A to apply the styles.
Inserts CSS rules globally (unscoped).
Works exactly like insertCss, but without prefixing selectors with a unique class name. This is useful for global resets, base styles, or styles that need to apply to the entire document.
Accepts the same concise style string syntax and CSS shortcuts as insertCss. See insertCss for detailed documentation on syntax and shortcuts.
Creates a new string that has the opposite sort order compared to the input string.
This is achieved by flipping the bits of each character code in the input string.
The resulting string is intended for use as a sort key, particularly with the
makeKey function in onEach, to achieve a descending sort order.
Warning: The output string will likely contain non-printable characters or appear as gibberish and should not be displayed to the user.
Reactively checks if an observable array or object is empty.
This function not only returns the current emptiness state but also establishes
a reactive dependency. If the emptiness state of the proxied object or array
changes later (e.g., an item is added to an empty array, or the last property
is deleted from an object), the scope that called isEmpty will be automatically
scheduled for re-evaluation.
Reactively maps/filters items from a proxied source array or object to a new proxied array or object.
It iterates over the target proxy. For each item, it calls func.
func returns a value, it's added to the result proxy under the same key/index.func returns undefined, the item is skipped (filtered out).The returned proxy automatically updates when:
target proxy.func call changes (for a specific item).Like copy, but uses merge semantics. Properties in dst not present in src are kept.
null/undefined in src delete properties in dst.
Attaches a reactive Aberdeen UI fragment to an existing DOM element. Without the use of
this function, A will assume document.body as its root.
It creates a top-level reactive scope associated with the parentElement. The provided
function func is executed immediately within this scope. Any proxied data read by func
will cause it to re-execute when the data changes, updating the DOM elements created within it.
Calls to A inside func will append nodes to parentElement.
You can nest derive or other A scopes within func.
Use unmountAll to clean up all mounted scopes and their DOM nodes.
Mounting scopes happens reactively, meaning that if this function is called from within another (derive or A or mount) scope that gets cleaned up, so will the mount.
Reactively maps items from a source proxy (array or object) to a target proxied object, where each source item can contribute multiple key-value pairs to the target.
It iterates over the target proxy. For each item, it calls func.
func returns an object, all key-value pairs from that object are added to the result proxy.func returns undefined, the item contributes nothing.The returned proxy automatically updates when:
target proxy.func call changes (for a specific item).This is useful for "flattening" or "indexing" data, or converting an observable array to an observable object.
Reactively iterates over the items of an observable array or object, optionally rendering content for each item.
Automatically updates when items are added, removed, or modified.
Reactively partitions items from a source proxy (array or object) into multiple "bucket" proxies based on keys determined by a classifier function.
This function iterates through the source proxy using onEach. For each item,
it calls the classifier func, which should return:
OUT_K): The item belongs to the bucket with this key.OUT_K[]): The item belongs to all buckets specified in the array.undefined: The item is not placed in any bucket.The function returns a main proxied object. The keys of this object are the bucket keys (OUT_K)
returned by func. Each value associated with a bucket key is another proxied object (the "bucket").
This inner bucket object maps the original keys/indices from the source to the items
themselves that were classified into that bucket.
The entire structure is reactive. Changes in the source proxy (adding/removing/updating items)
or changes in dependencies read by the func will cause the output partitioning to update automatically.
Buckets are created dynamically as needed and removed when they become empty.
Executes a function or retrieves a value without creating subscriptions in the current reactive scope, and returns its result.
This is useful when you need to access reactive data inside a reactive scope (like A) but do not want changes to that specific data to trigger a re-execute of the scope.
Note: You may also use unproxy to get to the raw underlying data structure, which can be used to similar effect.
Creates a reactive proxy around the given data.
Reading properties from the returned proxy within a reactive scope (like one created by A or derive) establishes a subscription. Modifying properties through the proxy will notify subscribed scopes, causing them to re-execute.
Proxy that intercepts
property access and mutations, but otherwise works like the underlying data.{ value: T } which is then proxied. Access the primitive via the .value property.{ busy: boolean, value?: T, error?: any }.
Initially, busy is true. When the promise resolves, value is set and busy
is set to false. If the promise is rejected, error is set and busy is also
set to false.Use unproxy to get the original underlying data back.
Creates a reactive reference ({ value: T }-like object) to a specific value
within a proxied object or array.
This is primarily used for the bind property in A to create two-way data bindings
with form elements, and for passing a reactive property to any of the A key-value pairs.
Reading ref.value accesses the property from the underlying proxy (and subscribes the current scope).
Assigning to ref.value updates the property in the underlying proxy (triggering reactive updates).
Forces the immediate and synchronous execution of all pending reactive updates.
Normally, changes to observed data sources (like proxied objects or arrays) are processed asynchronously in a batch after a brief timeout (0ms). This function allows you to bypass the timeout and process the update queue immediately.
This can be useful in specific scenarios where you need the DOM to be updated synchronously.
This function is re-entrant, meaning it is safe to call runQueue from within
a function that is itself being executed as part of an update cycle triggered
by a previous (or the same) runQueue call.
Sets a custom error handler function for errors that occur asynchronously within reactive scopes (e.g., during updates triggered by proxy changes in derive or A render functions).
The default handler logs the error to console.error and adds a simple
'Error' message div to the DOM at the location where the error occurred (if possible).
Your handler can provide custom logging, UI feedback, or suppress the default error message.
Initializes cssVars[0] through cssVars[12] with an exponential spacing scale.
The scale is calculated as 2^(n-3) * base, providing values from 0.25 * base to 512 * base.
Returns the original, underlying data target from a reactive proxy created by proxy.
If the input target is not a proxy, it is returned directly.
This is useful when you want to avoid triggering subscriptions during read operations or re-executes during write operations. Using peek is an alternative way to achieve this.
The main Aberdeen API.
Ais itself a callable function for building reactive DOM trees (creating elements, setting attributes, adding content). All other Aberdeen functions and values are available as properties onA.