# Global Helpers

This page covers `_` and `$`, the two DOM helpers QuickUI attaches to the global object when it loads.

## `$(selector)`

Returns a single element, `HTMLElement | null`.

```javascript
$("#app");
$("app");
$(".card");
$("input[name=email]");
$("button");
```

| Input | Lookup |
|---|---|
| Starts with `#` | `getElementById` with `#` removed |
| Contains `.`, `[` or `]` | `querySelector` |
| Anything else | `getElementById` first, then `querySelector` |

Only the first match is returned; use `document.querySelectorAll` when you need several.

## `_(selector, attributes?, children?)`

Creates an element from CSS selector syntax.

```javascript
_("div#card.box.shadow", { title: "Card", color: "red" }, [
  _("h2", "Title"),
  "plain text",
]);
_("img", "/logo.png");
_("temp", "text only");
```

| Argument | Description |
|---|---|
| `selector` | `tag#id.class`; must start with a tag or `undefined` is returned; `temp` creates a `DocumentFragment` |
| `attributes` | An object, see the table below |
| `children` | A string, number or array; with a single argument, a string / number / array is treated as `children` and an object as `attributes` |

| `attributes` key | Written as |
|---|---|
| `value`, `innerText`, `innerHTML`, `textContent`, `contentEditable` | Element property |
| `color`, `backgroundColor`, `width`, `height`, `display`, `float` | `style` |
| Anything else | `setAttribute`; skipped when the value is `null` or `undefined` |

| `children` type | Result |
|---|---|
| String or number | Written to `innerHTML`; `img` and `source` get `src` instead; `temp` creates a text node |
| Array | Appended in order; strings and numbers become text nodes, `Element` values are appended as is, anything else is skipped |

String `children` are written with `innerHTML`, so never pass unescaped user input.