Language Reference

input

A JavaScript object globally available in every template that gives access to the attributes it was provided from a custom tag or the data passed in through the top level api.

$signal

An AbortSignal available in all JavaScript statements and expressions.

It is aborted when

1. The expression is invalidated
2. The template or tag content is removed from the DOM

This is primarily to handle cleaning up side effects.

<script>
  document.addEventListener(
    "resize",
    () => {
      // this function will be automatically cleaned up
    },
    {
      signal: $signal,
    },
  );
</script>

script
  --
  document.addEventListener(
    "resize",
    () => {
      // this function will be automatically cleaned up
    },
    {
      signal: $signal,
    },
  );
  --

$global

Gives access the "render globals" provided through the top level api.

import

JavaScript import statements are allowed at the root of the template.

import sum from "sum";

<div data-number=sum(1, 2)/>

import sum from "sum";

div data-number=sum(1, 2)

import MyTag from "<my-tag>";

<MyTag/>

import MyTag from "<my-tag>";

MyTag

export

JavaScript export statements are allowed at the root of the template.

export function getAnswer() {
  return 42;
}

<div>${getAnswer()}</div>

export function getAnswer() {
  return 42;
}

div -- ${getAnswer()}

static

Statements prefixed with static allow running JavaScript expressions in module scope. The statements will run when the template loaded on the server and in the browser.

static const answer = 41;
static function getAnswer() {
  return answer + 1;
}

<div data-answer=getAnswer()/>

static const answer = 41;
static function getAnswer() {
  return answer + 1;
}

div data-answer=getAnswer()

All valid javascript statements are allowed, including functions, declarations, conditions, and blocks.

static console.log("this will be logged only ONE time");
static console.log("no matter how often the component is used");

static console.log("this will be logged only ONE time");
static console.log("no matter how often the component is used");

server and client

As an alternative to static, statements prefixed with server or client allow arbitrary module scoped JavaScript expressions that are exclusively executed when the template is loaded in a specific environment (the server or the browser).

server console.log("on the server");
client console.log("in the browser");

server console.log("on the server");
client console.log("in the browser");

All valid javascript statements are allowed, including functions, declarations, conditions, and blocks.

server import { connectToDatabase } from "./database";
server const db = connectToDatabase();

server {
  console.log("Database connection established on server");

  // Only happens ONCE, when the application loads
  // and this component is used for the first time
}
server const users = await db.query("SELECT * FROM users");
server console.log(`Found ${users.length} users in the database`);

server import { connectToDatabase } from "./database";
server const db = connectToDatabase();

server {
  console.log("Database connection established on server");

  // Only happens ONCE, when the application loads
  // and this component is used for the first time
}
server const users = await db.query("SELECT * FROM users");
server console.log(`Found ${users.length} users in the database`);

server import "./init-db";
client import "bootstrap";

server import "./init-db";
client import "bootstrap";

Skipped Attributes

If an attribute value is null, undefined or false it will not be written to the html.

Boolean Attributes

HTML boolean attributes become JavaScript booleans.

<input type="checkbox" checked>
<input type="checkbox" checked>

input type="checkbox" checked
input type="checkbox" checked

// ❌ WRONG: Don't do this

<button aria-pressed=isPressed/>
// outputs <button aria-pressed=""/>

// ❌ WRONG: Don't do this

button aria-pressed=isPressed
// outputs <button aria-pressed=""/>

// 👍 Correct use of aria attributes

<button aria-pressed=isPressed && "true"/>
// outputs <button aria-pressed="true"/>

// 👍 Correct use of aria attributes

button aria-pressed=isPressed && "true"
// outputs <button aria-pressed="true"/>

Spread Attributes

Attributes may be dynamically included with the spread syntax.

<my-tag ...input foo="bar"/>

my-tag ...input foo="bar"

In this case <my-tag> would receive the attributes as an object like { ...input, foo: "bar" }.

Attributes are merged from left to right, with later spreads overriding earlier ones if there are conflicts.

Shorthand Methods

Method definitions allow for a concise way to pass functions as attributes, such as event handlers.

<button onClick(ev) {
  console.log(ev.target);
}>
  Click Me
</button>

button onClick(ev) {
  console.log(ev.target);
}
  -- Click Me

Shorthand Change Handlers (Two-Way Binding)

The change handler shorthand (:=) provides both a value for an attribute and a change handler with the attribute's name suffixed by "Change".

The value must be an Identifier or a Property Accessor.

For Identifiers, the change handler desugars to a function with an assignment.

<counter value:=count/>
// desugars to


<counter
  value=count
  valueChange(newCount) {
    count = newCount;
  }
/>

counter value:=count
// desugars to


counter [
  value=count
  valueChange(newCount) {
    count = newCount;
  }
]

For Property Accessors, the change handler desugars to a member expression with a Change suffix.

<counter value:=input.count/>
// desugars to


<counter value=input.count valueChange=input.countChange/>

counter value:=input.count
// desugars to


counter value=input.count valueChange=input.countChange

Shorthand class and id

Emmet style class and id attribute shorthands are supported.

<div class="bar baz" id="foo"/>
// same as

<div id="foo" class="bar baz"/>

div.bar.baz#foo
// same as

div#foo.bar.baz

<div class=`icon-${iconName}`/>

div class=`icon-${iconName}`

Shorthand value

It is common for a tag to use a single input property; therefore Marko allows a shorthand for passing an attribute named value. If the attribute name is omitted at the beginning of a tag, it will be passed as value.

<my-tag=1/>
// desugars to


<my-tag value=1/>

my-tag=1
// desugars to


my-tag value=1

The method shorthand can be combined with the value attribute to give us the value method shorthand.

<my-tag() {
  console.log("Hello JavaScript!");
}/>
// desugars to


<my-tag value() {
  console.log("Hello JavaScript!");
}/>
// Received by the child as { value() { ... } }

my-tag() {
  console.log("Hello JavaScript!");
}
// desugars to


my-tag value() {
  console.log("Hello JavaScript!");
}
// Received by the child as { value() { ... } }

Attribute Termination

Attributes can be terminated with a comma. This is useful in concise mode.

<my-tag a=1 b=2/>

my-tag a=1 b=2

<my-tag a=(console.log(foo), foo)/>

my-tag a=(console.log(foo), foo)

Dynamic Text

Dynamic text content can be ${interpolated} in the tag content. This uses the same syntax as template literals in JavaScript.

<div>Hello ${input.name}</div>

div -- Hello ${input.name}

Nested Attribute tags

Attribute tags may be nested in other attribute tags.

<my-tag>
  <@a value=1>
    <@b value=2/>
  </@a>
</my-tag>

my-tag
  @a value=1
    @b value=2

Would provide the following as input

{
  a: {
    value: 2,
    b: { value: 2 }
  }
}

Repeated Attribute Tags

When multiple attribute tags share a name, all instances may be consumed using the iterable protocol.

<my-menu>
  <@item value="foo">
    Foo Item
  </@item>

  <@item value="bar">
    Bar Item
  </@item>
</my-menu>

my-menu
  @item value="foo" -- Foo Item

  @item value="bar" -- Bar Item

This example uses two <@item> tags, but <my-menu> receives only a single item attribute.

{
  item: {
    value: "foo",
    content: /* Foo Item */,
    [Symbol.iterator]() {
      // Not the exact implementation, but essentially this is what the function contains
      yield* [
        { value: "foo", content: /* Foo Item */ },
        { value: "bar", content: /* Bar Item */ }
      ];
    }
  }
}

The other <@item> tags are reached through the iterator. The most common way to do so is with a for tag or one of JavaScript's syntaxes for iterables.

<for|item| of=input.item>
  Value: ${item.value}
  <${item.content}/>
</for>

for|item| of=input.item
  -- Value: ${item.value}
  ${item.content}

<const/items=[...(input.item || [])]/>

<div>${items.length}</div>

const/items=[...(input.item || [])]

div -- ${items.length}

Conditional Attribute Tags

Attribute tags are generally provided directly to their immediate parent. The exception to this is control flow tags (<if> and <for>), which are used to dynamically apply attribute tags.

<my-message>
  <if=welcome>
    <@title>Hello</@title>
  </if>
  <else>
    <@title>Good Bye</@title>
  </else>
</my-message>

my-message
  if=welcome
    @title -- Hello
  else
    @title -- Good Bye

In this case, the @title received by <my-message> depends on welcome.

<my-select>
  <@option>None</@option>

  <for|opt| of=["a", "b", "c"]>
    <@option>${opt}</@option>
  </for>
</my-select>

my-select
  @option -- None

  for|opt| of=["a", "b", "c"]
    @option -- ${opt}

Here, <my-select> unconditionally receives the first @option, and also all of the @option tags applied by the <for> loop.

Scope

Tag variables are automatically hoisted and can be accessed anywhere in the template except for in module statements. This means that it is possible to read tag variables from anywhere in the tree.

<form>
  <input/myInput>
</form>

<script>
  // still available even though it's nested in another tag.
  console.log(myInput());
</script>

form
  input/myInput

script
  --
  // still available even though it's nested in another tag.
  console.log(myInput());
  --

Tag Arguments

Multiple tag parameters may be provided to the content by using the Tag Arguments syntax, which uses the JavaScript (...args) syntax after the tag name.

<${input.content}(1, 2, 3)/>

${input.content}(1, 2, 3)

This example passes three arguments back to its parent.

<my-tag|a, b, c|>
  Sum ${a + b + c}
</my-tag>
// spreads work also!

<my-tag|...all|>
  Sum ${all.reduce((a, b) => a + b, 0)}
</my-tag>

my-tag|a, b, c| -- Sum ${a + b + c}
// spreads work also!

my-tag|...all| -- Sum ${all.reduce((a, b) => a + b, 0)}

<my-tag a=1 b=2 c=3/>
// identical to

<my-tag({ a: 1, b: 2, c: 3 })/>

my-tag a=1 b=2 c=3
// identical to

my-tag({ a: 1, b: 2, c: 3 })

Scope

Tag parameters are scoped to the tag content only. This means you cannot access the tag parameters outside the body of the tag.

Dynamic Native Tags

When the value of the dynamic tag name is a string,

// Dynamically output a native tag.

<${"h" + input.headingSize}>Hello!</>

// Dynamically output a native tag.

${"h" + input.headingSize} -- Hello!

Dynamic Custom Tags

// Dynamically output a custom tag.

import MyTagA from "<my-tag-a>";
import MyTagB from "<my-tag-b>";
<${Math.random() > 0.5 ? MyTagA : MyTagB}/>

// Dynamically output a custom tag.

import MyTagA from "<my-tag-a>";
import MyTagB from "<my-tag-b>";
${Math.random() > 0.5 ? MyTagA : MyTagB}

<${Math.random() > 0.5 ? "my-tag-a" : "my-tag-b"}/>

${Math.random() > 0.5 ? "my-tag-a" : "my-tag-b"}

<define/Message>
  Hello World
</define>
<${Message}/>

define/Message -- Hello World
${Message}

Conditional Parent Tags

When a dynamic tag name is falsy it will output the tag's content only. This is useful for conditional parenting and fallback content.

// Only wrap the text with an anchor when we have an `input.href`.

<${input.href && "a"} href=input.href>
  Hello World
</>

// Only wrap the text with an anchor when we have an `input.href`.

${input.href && "a"} href=input.href -- Hello World

PascalCase Variables

Local variable names that start with an upper case letter (PascalCase) can also be used as tag names without the explicit dynamic tag syntax. This is useful for referencing an imported custom tag or with the <define> tag.

import MyTag from "./my-tag.marko";

<MyTag/>

import MyTag from "./my-tag.marko";

MyTag

This is equivalent to

import MyTag from "./my-tag.marko";

<${MyTag}/>

import MyTag from "./my-tag.marko";

${MyTag}