# Views > Views are pure functions from state to html templates. Name intents, render keyed lists, bind form state, and let the compiler check markup. Source: https://gyral.dev/docs/views/ A **view** is a function from state to HTML. It receives the state, the typed intent names `i`, and the context `{ props, read }`, and returns an `html` template. It has no other inputs and no side effects, so the same state always renders the same markup, on the server and in the browser. ```ts // src/profile.ts import { define, html } from '@gyral/core'; export interface State { readonly editing: boolean; readonly name: string; } export type Msg = { readonly _tag: 'Edit' } | { readonly _tag: 'Save'; readonly name: string }; export const Profile = define()('my-profile', { init: () => ({ editing: false, name: 'Ada' }), intent: { Edit: () => ({ _tag: 'Edit' }), Save: ({ formData }) => { const name = formData?.get('name'); return typeof name === 'string' ? { _tag: 'Save', name } : undefined; }, }, update: { Edit: (s) => ({ ...s, editing: true }), Save: (_s, m) => ({ editing: false, name: m.name }), }, view: (s, i) => html`

${s.name}

${ s.editing && html`
` } `, }); ``` ## Templates Everything a view needs comes from `@gyral/core`: `html`, `svg`, `css`, `nothing`, `each`, `keyed`, `raw` and `defineHook`. Gyral renders with its own small view layer, built for this one job: no virtual DOM, no runtime dependencies. A template is prepared once per call site. After that a render only compares each `${…}` with the value it wrote last time and touches the DOM where they differ. | Binding | Sets | | --------------------------- | ------------------------------------------------------------------------ | | `${value}` | Text content (escaped), a nested template, a list, or nothing | | `attr=${value}` | An attribute; `null`, `undefined` and `nothing` remove it | | `class="card ${s.kind}"` | An attribute built from several pieces (quote it) | | `?attr=${bool}` | A boolean attribute, present or absent | | `.prop=${value}` | A property: data for a child Gyral component, such as objects and arrays | | `` | An [element hook](#element-hooks) on that element | | `` | The textarea's value (see [Form state](#form-state)) | Boolean attributes (`selected`, `checked`, `disabled`, `open`, `required`, `hidden`'s siblings and the rest of HTML's list) take `?attr=${bool}`. Writing `selected=${bool}` would render `selected="false"`, which the browser reads as selected, so it's a template error with the fix in the message. In a text position, `false`, `null`, `undefined` and `nothing` render nothing, so ``${s.open && html`…`}`` works. Classes and inline styles are plain strings: `class=${s.done ? 'done' : ''}`, `style="--w: ${s.width}px"` (under a strict Content Security Policy, see [inline styles](https://gyral.dev/docs/styling/#inline-styles-under-a-strict-csp)). Inline `` works inside `html`, so icons and charts need nothing special; an SVG fragment that is a template of its own uses [`svg`](#svg-fragments). Property bindings carry data, never functions: events are [intents](#no-event-handlers), and behaviour on an element is a [hook](#element-hooks). Whitespace is normalized once per template, the same way on the server and in the browser: indentation between block-level tags disappears, and a run of whitespace between inline elements becomes one space. `
` and `` |

A binding writes the control only when the model's value for it changes. Then the model wins,
even after the user has edited the control (the view compares with what the control shows now
and writes only if they differ). A render for any other reason, such as another field's
message or a reducer that refused the edit, leaves what the user typed or toggled alone. On the
server the bindings write the attribute, so the page is right before JavaScript loads, and
hydration keeps what the user typed before scripts ran until the model's value changes.

To put a control back after a refused edit, change the model: clamp or normalize to a value
that differs from the one rendered last, or re-create the form with a key. Keep a counter in
the state, bump it on reset, and render `keyed(s.formKey, fields(s))`: the new key brings fresh
elements with the model's values. `form.reset()` is no substitute; it restores the first values, not the model's.

Never bind form state as a property (`.value=`, `.checked=`): the server can't write a
property, so the page would arrive empty. The compiler rejects it. A checkbox's `value` and a
`
    
      

        
Delete this task?

        
        
      

    
  `,
});
```

On the server neither binding writes anything; a dialog that should start open opens when the
component hydrates. Use `?open` only for a non-modal `` or `
`.

## Element hooks

A hook is a small behaviour attached to the element it sits on, written inside the start tag.
Core ships one, **`invalid(errors)`**, which mirrors model errors into native validity
(`setCustomValidity` and `aria-invalid`); see [Forms](https://gyral.dev/docs/forms/). Others are a few lines
each, such as capturing a pointer for [press-and-hold](https://gyral.dev/docs/intent/#press-and-hold).

Write your own with `defineHook`. `client(el, args, prev)` runs after the render whenever the
arguments change (`prev` is `undefined` the first time). An optional `server(args)` returns
attributes for the server-rendered start tag, so the page is right before scripts run. A hook
acts only on its own element, and listeners it adds there go away with the element, so most
hooks need no teardown:

```ts
// src/steps.ts
import { define, defineHook, html } from '@gyral/core';

/** Marks the current step, and scrolls it into view when it becomes current. */
export const currentStep = defineHook<[active: boolean]>({
  // The server writes the attribute into the start tag, so it's there before scripts run.
  server: ([active]) => (active ? { 'aria-current': 'step' } : {}),
  client: (el, [active], prev) => {
    if (active) el.setAttribute('aria-current', 'step');
    else el.removeAttribute('aria-current');
    if (active && prev !== undefined && !prev[0]) el.scrollIntoView({ block: 'nearest' });
  },
});

export interface State {
  readonly current: number;
}

export type Msg = { readonly _tag: 'Next' };

export const Steps = define()('my-steps', {
  init: () => ({ current: 0 }),
  intent: { Next: () => ({ _tag: 'Next' }) },
  update: { Next: (s) => ({ current: (s.current + 1) % 3 }) },
  view: (s, i) => html`
    
    
      
  1. Choose
    2. 
      
  2. Pay
    3. 
      
  3. Done
    4. 
    

    
  `,
});
```

Hooks run after the whole render, children before parents, so a parent's hook can measure the
children that just rendered. A hook runs again when its arguments change; pass
`update: 'always'` to `defineHook` for one that runs after every render of its component, such
as a hook that keeps a scroll position anchored while a list grows.

### Custom properties

To hand a value to CSS, bind a custom property in a `style` attribute and let the stylesheet
use it, with a fallback:

```ts
// src/upload-progress.ts
import { css, define, html, prop, type Stateless } from '@gyral/core';

export interface Props {
  readonly sent: number;
  readonly total: number;
}

export const UploadProgress = define()('my-upload-progress', {
  props: { sent: prop.number({ default: 0 }), total: prop.number({ default: 1 }) },
  intent: {},
  update: {},
  view: (_s, _i, { props }) => html`
    

    
${props.sent} of ${props.total} files

  `,
  styles: css`
    .bar {
      block-size: 0.5rem;
      background: linear-gradient(to right, currentColor calc(var(--fill, 0) * 100%), #0000 0);
    }
  `,
});
```

Gyral writes `style` bindings through the CSSOM, so they work under a Content Security Policy
without `'unsafe-inline'`. In server-rendered markup such a policy blocks the attribute until the
component hydrates, which is why the stylesheet keeps a default, `var(--fill, 0)`. [Inline styles
under a strict CSP](https://gyral.dev/docs/styling/#inline-styles-under-a-strict-csp) has the details.

A `style` binding owns the whole attribute. For the rare element whose inline style a hook
writes too, let a hook set only the properties it names:

```ts
// src/css-vars.ts
import { defineHook } from '@gyral/core';

/** Sets the named custom properties, leaving the element's other inline styles alone. */
export const cssVars = defineHook<[vars: Readonly>]>({
  client: (el, [vars]) => {
    if (!(el instanceof HTMLElement)) return;
    for (const [name, value] of Object.entries(vars)) el.style.setProperty(name, value);
  },
});
```

### Replaying a CSS animation

A CSS animation runs once, when its element appears. A "flash on change", such as an unread
badge that pulses when a message arrives or a field that shakes on a rejected value, has to
replay it. Count the replays in state, and restart the element's animations with the Web
Animations API when the count changes:

```ts
// src/inbox-badge.ts
import { css, define, defineHook, html } from '@gyral/core';

/** Restarts the element's CSS animations whenever `count` changes, not on the first render. */
export const replay = defineHook<[count: number]>({
  client: (el, [count], prev) => {
    if (prev === undefined || prev[0] === count) return;
    for (const animation of el.getAnimations()) {
      animation.cancel();
      animation.play();
    }
  },
});

export interface State {
  readonly unread: number;
  readonly pulses: number;
}

export type Msg = { readonly _tag: 'Arrived' };

export const InboxBadge = define()('my-inbox-badge', {
  init: () => ({ unread: 0, pulses: 0 }),
  intent: { Arrived: () => ({ _tag: 'Arrived' }) },
  update: { Arrived: (s) => ({ unread: s.unread + 1, pulses: s.pulses + 1 }) },
  view: (s, i) => html`
    ${s.unread}
    
  `,
  styles: css`
    .badge {
      animation: pulse 300ms ease-out;
    }
    @keyframes pulse {
      50% {
        scale: 1.3;
      }
    }
    @media (prefers-reduced-motion: reduce) {
      .badge {
        animation: none;
      }
    }
  `,
});
```

`getAnimations()` covers the CSS animations and transitions running on the element; pass
`{ subtree: true }` to include its descendants. The count lives in state because the model
decides when something deserves attention, and a count, unlike a boolean, changes every time.
Without a hook, `keyed(s.pulses, Badge(s))` replays by replacing the element, at the cost of a
new node (and its focus, if it had any).

## Widgets with a lifecycle

Something with setup and teardown, such as a WebGL stage, a chart or map library, an observer or
a connection, has a native home: **a custom element of its own**. Give it one property for its
input, keep its state inside, set up in `connectedCallback` and tear down in
`disconnectedCallback`. The browser then tells it about every connect, disconnect and move, the
view stays a description of data, and the widget can be tested on its own:

```ts
// src/scene-editor.ts
import { define, html } from '@gyral/core';

interface Scene {
  readonly cubes: number;
}

/** The widget: one property in, its own lifecycle. */
class StageElement extends HTMLElement {
  #scene: Scene = { cubes: 0 };
  #frame = 0;

  set view(scene: Scene) {
    this.#scene = scene;
    this.#schedule();
  }

  connectedCallback(): void {
    this.#schedule(); // set up the renderer, canvas and observers here
  }

  disconnectedCallback(): void {
    cancelAnimationFrame(this.#frame); // dispose the renderer and listeners here
  }

  #schedule(): void {
    cancelAnimationFrame(this.#frame);
    this.#frame = requestAnimationFrame(() => {
      this.textContent = `${String(this.#scene.cubes)} cubes`;
    });
  }
}
customElements.define('my-stage', StageElement);

interface State {
  readonly scene: Scene;
}

type Msg = { readonly _tag: 'Add' };

export const SceneEditor = define()('my-scene-editor', {
  init: () => ({ scene: { cubes: 1 } }),
  intent: { Add: () => ({ _tag: 'Add' }) },
  update: { Add: (s) => ({ scene: { cubes: s.scene.cubes + 1 } }) },
  view: (s, i) => html`
    
    
  `,
});
```

The widget reports back with events: it dispatches
`new CustomEvent(OUTPUT_EVENT, { detail: { _tag: 'Picked' }, bubbles: true })` on itself, and the
parent parses that like a [child component's output](https://gyral.dev/docs/components/#outputs-and-other-code).
When the widget has a model of its own, make it a Gyral component (`prop.value` for its input,
`outputs()` for its events).

For a **small imperative behaviour** on an element of the view, such as a timer, a
`ResizeObserver` or a third-party enhancer on one input, a hook with a teardown is lighter:
`defineHook` takes `dispose(el, args)` next to `client`.

```ts
// src/flash.ts
import { defineHook } from '@gyral/core';

const timers = new WeakMap>();

/** Highlights the element for a moment whenever `value` changes. */
export const flash = defineHook<[value: unknown]>({
  client: (el, _args, prev) => {
    if (prev === undefined) return; // not on the first render
    el.classList.add('flash');
    clearTimeout(timers.get(el));
    timers.set(
      el,
      setTimeout(() => {
        el.classList.remove('flash');
      }, 600),
    );
  },
  dispose: (el) => {
    clearTimeout(timers.get(el));
  },
});
```

- `dispose` runs when Gyral removes the element (its part cleared, its template replaced, its
  list row removed), when the position stops holding the hook, and when the component
  disconnects. It never runs for moves: rows reordered in a list, or a component moved with
  `moveBefore()`.
- After a component disconnects and reconnects, `client` runs again with `prev` undefined.
- The teardown tracking is bundled only when some hook has a `dispose`, so apps whose hooks
  need none don't pay for it.

## Trusted markup with raw()

`raw(markup)` renders a string as HTML: Markdown you converted at build time, highlighted code,
a JSON-LD script. Use it only for markup your own code produced, never for user input. It
belongs mostly on the server: in a component that renders in the browser, every change parses
the string again, and development mode warns about it. This site renders every docs page with
`raw()` inside a server-only template.

## Focus is a command

Moving focus is a side effect, so it comes from `update`, not the view. `focus(selector)`
focuses the first match in the component once the update has rendered, so it can target an
element the same update creates:

```ts
// src/pager.ts
import { define, focus, html } from '@gyral/core';

export interface State {
  readonly page: number;
}

export type Msg = { readonly _tag: 'Next' };

export const Pager = define()('my-pager', {
  init: () => ({ page: 1 }),
  intent: { Next: () => ({ _tag: 'Next' }) },
  update: {
    // Move focus to the new page's heading, as a screen reader user would expect.
    Next: (s) => [{ page: s.page + 1 }, [focus('h2', { preventScroll: true })]],
  },
  view: (s, i) => html`
    
Page ${s.page}

    
  `,
});
```

Headings aren't focusable by default, hence `tabindex="-1"`.

### Focusing what a later render brings

`focus()` runs after the render its update caused. When the target only appears later, such as
the first result once a search answers, pass `wait: true`: the request stays pending until a
render of the component produces the target. A newer `focus()` from the component replaces it,
and after one second it gives up with the usual warning. `settled()` doesn't wait for it.

```ts
// src/result-search.ts
import { command, define, defineDriver, focus, html } from '@gyral/core';

interface Result {
  readonly id: string;
  readonly title: string;
}
export interface State {
  readonly query: string;
  readonly results: readonly Result[];
}
export type Msg =
  | { readonly _tag: 'Search'; readonly query: string }
  | { readonly _tag: 'Found'; readonly results: readonly Result[] };

const search = defineDriver({
  name: 'search',
  run: async (query, { signal }) => {
    const response = await fetch(`/api/search?q=${encodeURIComponent(query)}`, { signal });
    return (await response.json()) as readonly Result[];
  },
});

export const ResultSearch = define()('my-result-search', {
  init: () => ({ query: '', results: [] }),
  intent: {
    Search: ({ formData }) => ({ _tag: 'Search', query: String(formData?.get('q') ?? '') }),
  },
  update: {
    // The first result exists only after `Found` renders: the focus waits for it.
    Search: (s, m) => [
      { ...s, query: m.query },
      [
        command(search, m.query, { onSuccess: (results): Msg => ({ _tag: 'Found', results }) }),
        focus('#results li:first-child a', { wait: true }),
      ],
    ],
    Found: (s, m) => ({ ...s, results: m.results }),
  },
  view: (s, i) => html`
    

      
      
    

    
  `,
});
```

### Focusing into a child component

`focus()` looks inside the component's own root, so it can't reach an element in a child's
shadow root. Give the child `shadow: { delegatesFocus: true }` and focus the child itself:
focusing the host then focuses its first focusable element.

```ts
// src/name-field.ts
import { define, html, type Stateless } from '@gyral/core';

/** Focusing  focuses its input. */
export const NameField = define()('my-name-field', {
  shadow: { delegatesFocus: true },
  intent: {},
  update: {},
  view: () => html``,
});
```

```ts
// src/contact-form.ts
import { define, focus, html, type Stateless } from '@gyral/core';
import './name-field.js';

export type Msg = { readonly _tag: 'Edit' };

export const ContactForm = define()('my-contact-form', {
  intent: { Edit: () => ({ _tag: 'Edit' }) },
  update: { Edit: (s) => [s, [focus('my-name-field')]] },
  view: (_s, i) => html`
    
    
  `,
});
```

The same delegation works for `el.focus()` from page script and for a click on a part of the
child that can't take focus, and `:focus` matches the host while focus is inside it. The server
writes `shadowrootdelegatesfocus` on the declarative shadow root, so a server-rendered child
delegates focus before and after hydration.

### Keeping focus across renders

Focus stays only as long as the focused element does. When a render removes it, the browser
moves focus to the page body. Render focusable rows with a keyed `each`, so a row moves instead
of being created again, and when the focused item really goes away, such as a deleted row,
return a `focus()` command for its neighbour or for the list.

## Calling a method on an element

Some elements are driven by methods: a `