Getting started

Add Asgard

From your EkkoJS project root:

00000000001
ekko add @ekko/asgard

That records @ekko/asgard in your ekko.json and installs it into the store. No bundler config, no peer-dependency juggling.

Wrap your app

Asgard components read their colors from a ThemeProvider. Add one near the root of your app and feed it a theme:

00000000001
2
3
4
5
6
7
8
9
10
import { ThemeProvider, Button } from "@ekko/asgard";
import { themes } from "@ekko/asgard/theme";
 
export default function App() {
  return (
    <ThemeProvider theme={themes.nord}>
      <Button variant="filled">Hello, Asgard</Button>
    </ThemeProvider>
  );
}

themes is a map of 27 built-in palettes. Swap themes.nord for themes.dracula, themes.githubLight, themes.tokyoNight, etc., or pass your own object. Object.keys(themes) is the source of truth for the exact key names (note the casing, e.g. onedark, ayuDark/ayuLight, materialDark/materialLight). See Theming for the full list, the token reference, and the <ThemeCssVars/> bridge that re-themes your own SCSS on switch.

With a rune page

In a ekko:rune app, drop components straight into a page, they render on the server and hydrate on the client:

00000000001
2
3
4
5
6
7
8
9
10
11
// pages/index.tsx
import { ThemeProvider, Alert } from "@ekko/asgard";
import { themes } from "@ekko/asgard/theme";
 
export default function Home() {
  return (
    <ThemeProvider theme={themes.nord}>
      <Alert severity="success" title="It works">You're rendering Asgard on the server.</Alert>
    </ThemeProvider>
  );
}

Imports

Components and hooks: @ekko/asgard
Themes and theme types: @ekko/asgard/theme

00000000001
2
import { Button, TextBox, DataTable, useTheme, ThemeCssVars } from "@ekko/asgard";
import { themes, type Theme } from "@ekko/asgard/theme";

The CSS-vars bridge (ThemeCssVars, applyThemeToRoot, themeToCssVars) is exported from @ekko/asgard, the same root as the components and hooks.

A note on input events

Asgard inputs are controlled and hand your onChange the value directly, not a DOM event, so write onChange={(v) => setX(v)}, not e.target.value. <Button> is the exception (it isn't a value input); it uses onClick with the mouse event, and renders type="button" by default (pass htmlType="submit" to submit a form). See Theming for the full per-input table.

Text inputs also forward the standard onFocus, onBlur, and onKeyDown handlers to the underlying <input>, so "submit on Enter" works: <TextBox value={v} onChange={setV} onKeyDown={(e) => { if (e.key === "Enter") add(); }} />.

One rendering note for <TextBox>: by default the placeholder text floats as a <label> (the placeholderBehavior="float" default), so the rendered <input> has an empty placeholder="" attribute. If you inspect or test the HTML, look for the label text, not an <input placeholder="…">. Pass placeholderBehavior="disappear" to render a plain native input placeholder instead (the two valid values are "float" and "disappear").

Verifying server-rendered output. Asgard components render with generated element IDs (e.g. id="textbox-Rbe", id="checkbox-...") and themed inline styles, not stable semantic class names. To confirm a component rendered in the SSR HTML, look for its generated id prefix (the component name) and the themed inline styles, not for a CSS class like asgard-button.

Theming, the palette system and custom themes.
Layout and Docking, build full app shells.
Components by category.

On this page

Add Asgard Wrap your app With a rune page Imports A note on input events Next