---
name: aberdeen
description: Expert guidance for building reactive UIs with the Aberdeen library. Covers element creation, reactive proxy state, efficient list rendering, CSS shortcuts, UI components, routing, transitions, and optimistic updates.
---
Aberdeen is a reactive UI library using fine-grained reactivity via JavaScript Proxies. No virtual DOM, no build step required.
# Guidance for AI Assistants
1. **Never concatenate user data** - Use `A('input value=', data)` not `A('input value=${data}')`
2. **Pass observables directly** - Use `text=', ref(obj, 'key')` to avoid parent scope subscriptions
3. **Use `onEach` for lists** - Never iterate proxy arrays with `for`/`map` in render functions
4. **Class instances are great** - Better than plain objects for typed, structured state
5. **CSS shortcuts** - Use $3, $4 for spacing (1rem, 2rem), $primary for colors (assuming setVarSpacingCssVars is used and cssVars colors are defined)
6. **Minimal scopes** - Smaller reactive scopes = fewer DOM updates
7. **Function components** - Create reusable UI components as regular functions starting with 'draw' (like drawMainMenu(settings) or drawProfilePage(user))
8. **Prefix proxied objects** - As a convention, prefix variable names that contain proxied objects with '$' (e.g. `$user`, `$settings`)
9. **Think about rerenders** - When you read from a proxied object (like `let n = $user.name;`), the containing A(() => {..}) or A('div', () => {}) function will rerun on change - plan on which level you want updates to trigger
# Tutorial
## Creating elements
This is a complete Aberdeen application:
```javascript
import A from 'aberdeen';
A('h3#Hello world');
```
It adds a `Hello world
` element to the `` (which is the default mount point).
The {@link aberdeen.A} function accepts various forms of arguments, which can be combined.
When a string is passed:
- The inital part (if any) is the name of the element to be created.
- One or multiple CSS classes can be added to the 'current' element, by prefixing them with a `.`.
- Content text can be added by prefixing it with a `#`. This has to be the last thing in the string: the text runs on to the end of it, so anything written after the `#` becomes part of the text.
Instead of the `#` prefix for text content, you can also use the `text=` property, like this: `A('h3 text="Hello world"')`. The double quotes are needed here only because our text contains a space. This is also how to give an element text when more should follow in the same string, as `#` would swallow it: `A('button text=Undo click=', undo)` does what you'd expect, while `A('button #Undo click=', undo)` gives you a button labelled `Undo click=` — and, since nothing is left waiting for it, `undo` is taken as a content function and run right there.
For simple formatting, use `rich=` which supports `*italic*`, `**bold**`, `` `code` ``, and `[links](url)`:
```javascript
A('p rich="This is *italic*, **bold**, and `code` with a [link](/path)."');
```
`A()` can accept multiple strings, so the following lines are equivalent:
```javascript
A('button.outline.secondary#Pressing me does nothing!');
A('button', '.outline', '.secondary', '#Pressing me does nothing!');
```
Also, we can create multiple nested DOM elements in a single {@link aberdeen.A} invocation, *if* the parents need to have only a single child. For instance:
```javascript
A('div.box', '#Text within the div element...', 'input');
```
Note that you can play around, modifying any example while seeing its live result by pressing the *Edit* button that appears when hovering over an example!
In order to pass in additional properties and attributes to the 'current' DOM element, we can use the `key=value` or `key=`, value syntax. So to extend the above example:
```javascript
A('div.box id=cityContainer input value=London placeholder=City');
```
Note that `value` doesn't become an HTML attribute. This (together with `selectedIndex`) is one of two special cases, where Aberdeen applies it as a DOM property instead, in order to preserve the variable type (as attributes can only be strings).
When a value ends with `=`, the next argument is used as its value. This is used for dynamic values and event listeners. So to always log the current input value to the console you can do:
```javascript
A('div.box input value=Marshmallow input=', el => console.log(el.target.value));
```
Note that the example is interactive - try typing something!
> **Note:** {@link aberdeen.A} also accepts object syntax as an alternative to strings (see the API reference), but the string syntax shown here is more concise and is recommended for most use cases.
## Inline styles
To set inline CSS styles on elements, use the `property:value` (short form) or `property: value containing spaces;` (long form) syntax:
```javascript
A('p color:red padding:8px background-color:#a882 border: 2px solid #a884; #Styled text');
```
### Property shortcuts
Aberdeen provides shortcuts for commonly used CSS properties, making your code more concise.
| 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` |
```javascript
A('div mv:10px ph:20px bg:lightblue r:10% #Styled box');
```
### CSS variables
Values starting with `$` expand to native CSS custom properties via `var(--name)`. The {@link aberdeen.cssVars | A.cssVars} object offers a convenient way of setting and updating CSS custom properties at the `:root` level.
When you add the first property to `A.cssVars`, Aberdeen automatically creates a reactive `