GitHub - oriolmrt/act: A scripting language for HTML

Caution

This is not even a beta. Breaking changes may occur without notice.

<script src="act.js"></script>
<button act@click="alert: `Just act, don't react!`">Click me!</button>

<button id="hide-btn">When I'm clicked I will hide after 1 second.</button>
...
<script>
    document.addEventListener('DOMContentLoaded', () => {
        document.getElementById('hide-btn').addEventListener('click', (e) => {
            setTimeout(() => {
                e.target.style.display = 'none';
            }, 1000);
        });
    });
</script>

<button onclick="setTimeout(() => { this.style.display = 'none'; }, 1000);">When I'm clicked I will hide after 1 second.</button>

<button id="hide-btn">When I'm clicked I will hide after 1 second.</button>
...
<!-- A lot of HTML later... -->
<script>
    $(document).ready(function() {
        $('#hide-btn').click(function(e) {
            setTimeout(function() {
                $('#hide-btn').hide();
            }, 1000);
        });
    });
</script>

npx create-react-app my-app

<button act@click="wait: 1s; hide!;">When I'm clicked I will hide after 1 second.</button>

<script src="act.js"></script>

<button 
    act="fade: out 500ms; fade: in 500ms; repeat;"
    act@click="kill act"
>
    I will stop fading in and out when you click me!
</button>


<div id="one" style="width: 100px; height: 100px; background-color: red;">
    <script type="text/act">
        transition: color to blue in 1s; 
        transition: color to red in 1s;
        repeat;
    </script>
</div>
<div id="two" style="width: 100px; height: 100px; background-color: green;">
    <script type="text/act">
        transition: color to yellow in 1s; 
        transition: color to green in 1s; 
        repeat;
    </script>
</div>
<button act@click="#one toggle!; #two toggle!">Toggle divs</button>
<button act@click="#one kill act; #two kill act">Stop animations</button>


<h1>AI Dinner suggester 2000</h1>
<ul id="dinner-list" act@click:target="confirm: `Remove {:inner_text}?` ? remove!">
    <li>Pizza</li>
    <li>Pasta</li>
    <li>Salad</li>
    <li>Sushi</li>
    <li>Steak</li>
</ul>
<button class="button">
    <script type="text/act" act@click>
    with new <li>, do
        $name: prompt: 'Name of the dinner item:';
        not $name? stop;
        << $name;
        #dinner-list append: me;
    end;
    </script>
    Add a new dinner item
</button>
<button class="button"> 
    <script type="text/act" act@click>
        $items: {#dinner-list li};
        $decided: random: 0 ($items.length - 1);
        alert: `Today I suggest {$items[$decided].inner_text} for dinner!`;
    </script>
    Decide dinner!
</button>

Note

Remember to follow a healthy diet, exercise regularly, and drink plenty of water.

<button act@click="fade: out">Click to fade out</button>

<button>
    <script type="text/act" act@click>
        fade: out;
        wait: 1s;
        fade: in;
    </script>
    Click me
</button>

#box1 hide!;
wait: 1s;
#box2 show!;
#box3 fade: in 1s&   // & terminator is used to run the sentence asynchronously
#box4 fade: out 1s;

#my-element hide!;              // Target: #my-element, Operation: call hide
$name: 'John';                  // Operation: assignment
alert: 'Hello!';                // Operation: call alert

#element hide!;                  // No arguments
#element fade!: out 500ms;       // With arguments
$array push!: 'item';            // Method on a variable

#input :value;                  // DOM property (:)
#element *background-color;     // CSS property (*)
#element @disabled;             // HTML attribute (@)

// Set (when left is a property, attribute, CSS property, or variable)
#input :value: 'text';           // Property: sets value
#input value: 'text';            // Word that resolves to a property: sets value
#element *background: red;       // CSS property: sets background
#button @disabled: true;         // Attribute: sets disabled
$name: 'John';                   // Variable: sets variable

// Call (when left is a word/method name)
fade: in 500ms;                  // Word: calls fade method
alert: 'Hello!';                 // Word: calls alert function

#input :value = 'text';           // Property: sets value
#input value = 'text';            // Word that resolves to a property: sets value
#element *background = red;       // CSS property: sets background
#button @disabled = true;         // Attribute: sets disabled
$name = 'John';                   // Variable: sets variable

$Global_var: 'accessible everywhere';
$scoped_var: 'only in this scope';

global $global_var: 'accessible everywhere';
local $local_var: 'only in this element';
scoped $scoped_var: 'only in this scope';

#my-id                          // ID selector
.my-class                       // Class selector (returns collection)
<div>                           // Tag selector (returns collection)
{div > .item}                   // Selector template (query)

each $item in $list (
    log: $item;
);

if $name is 'John' (
    alert: 'Hello John!';
);

(
    wait: 1s;
    show!;
);

do
    $x: 10;
    log: $x;
    (
        log: `I will print 10: {$x}`;
    );
end;

do
    log: $x;  // It will not print 10 as this is a different scope and $x is not defined.
end;

$sum: 1 + 2;
$product: 3 * 4;
$is_equal: $a is $b;
$is_greater: $x > 5;

$name: 'World';
log: `Hello, {$name}!`;         // Interpolate variables
log: `Sum: {1 + 2}`;            // Interpolate expressions

Note

Automatic Case Conversion & JavaScript Method Access

When accessing properties or calling methods, act automatically converts snake_case to camelCase. This means you can write :inner_text to access innerText, or query_selector_all to call querySelectorAll.

You can call any native JavaScript method on values using this conversion. For example:

• $number.to_string: 16 calls the native toString(16) method
• #my-element focus! calls the native focus() method
• $string.to_upper_case! calls the native toUpperCase() method

This makes act seamlessly integrate with the entire JavaScript API using the superior snake_case.

Tip

Append ! after a selector template (or any DOM Reference like .class or <tag>) to select the first matching element directly, instead of returning a NodeList. This is equivalent to using querySelector instead of querySelectorAll.

{> a.active}!     // first matching <a class="active"> inside the current element
.button!          // first element with class 'button'
<li>!            // first <li> element on the page

<div id="user-profile">
    <input type="text" name="user-name" act@input="$Name: :value">
    <!-- ... -->
</div>
<!-- ... -->
<!-- Somewhere else on the page -->
<div id="some-other-div">
    <button id="some-other-action">
        <script type="text/act" act@click>
            not $Name?
                alert: 'Please complete your profile first!'
            ~ do
                $Name is 'John'? 
                    alert: 'Sorry but John is not allowed to do that.'
                ~ 
                    alert: 'OK!';
            end;
        </script>
        Do some stuff!
    </button>
</div>

Note

Global variables are stored in the body element. The variable lookup code goes directly to the body element when the variable name starts with a capital letter or the global prefix is used.

<div id="some-div" act="local $some_var: 1; $another_var: 1;"><!-- Both variables are 1 -->
    <button id="some-button" act@click="alert: `$some_var is {$some_var}, and $another_var is {$another_var}`">
        Click me!
    </button>
</div>

<div act="local $foo: 1">
    <!-- Here $foo is 1, $bar is undefined, $baz is undefined -->
    <div act="local $bar: 2">
        <!-- Here $foo is 1, $bar is 2, $baz is undefined -->
        <div act="local $baz: 3">
            <!-- Here $foo is 1, $bar is 2, $baz is 3 -->
        </div>
    </div>
</div>

<section id="some-section" act="local $section_var: 3">
    <div id="some-div" act="scoped $some_var: 1; local $another_var: 1; log: $section_var;">

        <button id="some-button"> 
            <script type="text/act" act@click>
                // Here $some_var is undefined, not defined in the same Scope.
                // $another_var is 1, as it is declared at the local scope.
                alert: `$some_var is {$some_var}, and $another_var is {$another_var}`;

                scoped $foo: 10;

                do
                    log: $foo;  // $foo looked up. Logs 10.
                    scoped $foo: 20;  // $foo defined as a scoped variable in THIS Scope.
                    log: $foo;  // Logs 20.
                    log: $section_var;  // Logs 3. $section_var is available as a local variable of a parent element.
                end;

                log: $foo;  // Logs 10.
            </script>
            Click me!
        </button>
    </div>
</section>

run my_block from #component arg1 arg2;

<div id="user-profile">
    <script type="text/act" act-block="check_field $border_color">
        if value.length < 2 or :value is 'John' (
            *border: 5px solid $border_color;
            @invalid: true;
            first {> .field-info} << 'Please enter a valid name';
         ) else (
            *border: 1px solid green;
            remove_attribute: invalid;
            first {> .field-info} << empty!;
        );
    </script>
    
    <input type="text" act@input="debounce: 250ms run check_field firebrick;">
    <p class="field-info"></p>
    
    <input type="text" act@input="debounce: 250ms run check_field orangered;">
    <p class="field-info"></p>
</div>

<script type="text/act" act-block="greet $name $title">
    alert: `Hello {$title} {$name}!`;
</script>

<button act@click="run greet 'Smith' 'Dr.'">Greet Dr. Smith</button>
<button act@click="run greet 'Johnson' 'Prof.'">Greet Prof. Johnson</button>

Warning

While act blocks are useful, avoid overusing them or you'll end up searching for where things are defined and what they do, which can get messy fast. Don't jQueryit.

<div id="just-a-squared-div" class="square" style="width: 100px; height: 100px; background-color: red;"></div>
<div id="another-squared-div" class="square" style="width: 100px; height: 100px; background-color: green;"></div>

<button class="toggable" act@click="#just-a-squared-div *background-color: red">
    Make the first square background red
</button>
<button class="toggable" act@click="<div>[0] *background-color: green">
    Make the first square background green
</button>
<button class="toggable" act@click="first {.square} *background-color: blue">
    Make the first square background blue
</button>
<button class="toggable" act@click="<div> each (*background-color: `rgb({random: 0 255}, {random: 0 255}, {random: 0 255})`)">
    Random background for both divs!
</button>
<button act@click=".toggable each toggle!">
    Toggle the buttons
</button>

// Synchronous execution (;) - waits for each step
wait: 0.5s;
log: "I'll be logged after 0.5 seconds.";
#some-element transition: background-color to red in 2s;
log: "I'll be logged after the transition ends (2 seconds).";

// Asynchronous execution (&) - doesn't wait
#some-element transition: background-color to green in 3.5s &
log: "I'll be logged immediately. The transition runs in the background.";

// Conditional execution (?)
$a_variable: true;
$a_variable? log: "I'll be logged because $a_variable is true.";

// Conditional with else
$a_variable?
    log: "I'll be logged because $a_variable is true."
~
    log: "This sentence will be skipped.";

left (operation token) right1 right2 right3

log: has_attribute: data-someattr, 2 + 3

// Declaring a simple function to use later:
$greet: -> $name (
    alert: `Hello {$name}!`;
);

#some-div hide!;  
// Calls the hide method for an Element target type from the act Library.

alert: 'Hello world!';  
// No method 'alert' found on the Library or the target, falling back to window and calling window.alert.
alert('Hello world!');
// This also works but it's less fun.

$greet: 'Foo';  
// Calls the anonymous function with the argument 'Foo'.

$greet('Foo');  // Calls the anonymous function with the argument 'Foo' again, using parentheses syntax.

#some-div *border = '1px solid red';  
// Sets the CSS property border of #some-div to 1px solid red.

$a = 1;  
// Declares or sets the variable $a to 1.

$b[3] = 'foo';
$c.property = 'bar';
// It also sets members of arrays and properties of objects.

<button>[4] @disabled = true;  
// Sets the disabled attribute of the 5th button to true.

#long-text inner_html = 'tl;dr';  
// Sets the inner_html property of #long-text to 'tl;dr'.

#short-text (inner + HTML) = 'wall of text here';  
// Sets the inner_html property of #short-text. The value is a scope that evaluates to the concatenated words 'inner' and 'HTML', so you can effectively use any value as long as it evaluates to a string.

#medium-text `inner{'html'.to_upper_case!}` = 'meh';  
// Sets the inner_html property of #medium-text to 'meh'. Again, the value in this case is not a word but a string template.

*border: 1px solid red;  
// CSS property as left operand: uses a set operation and sets the border property to 1px solid red.
// With CSS properties the right operands list is joined with a space.

$a: 1;  
// Variable as left operand: uses a set operation and sets the variable $a to 1.

@disabled: true;  
// Attribute as left operand: uses a set operation and sets the disabled attribute to true.

:property: 5;
// Property as left operand: uses a set operation and sets the property to 5.

fade: in 100ms;  
// Word as left operand: uses the call operation and calls the fade method of the act Library with the right operands 'in' and '100ms'.

inner_html: 'bah';  
// Word as left operand: uses the call operation, as no method is found sets the inner_html property to 'bah'.

$fruits: [Orange Apple Banana];
$human: [
    name: 'John'
    say_hello: ->(
        log: `My name is {$this.name}!`;
    )
];

$human.say_hello!;
// Logs 'My name is John!'.

$human.name: 'Johnny';  // Or $human[name] = 'Johnny';
$human.say_hello!;
// Logs 'My name is Johnny!'.

$fruits[0]: 'Apricot';
$fruits.push: 'Peach';
log: $fruits[4].to_upper_case!;  
// It calls the toUpperCase method of the string 'Peach' and logs 'PEACH'.

$user: null;
$user?.name;        // undefined, no throw

$data: [meta: null];
$data.meta?.title;  // undefined: .meta is safe, .title propagates

Note

One more expression, insert (<<), appends content into a single element or pushes into an array. Because it reads like an operator, it's documented in Operators (#div << 'Content').

Important

Strict Operator Spacing Operators MUST be surrounded by spaces.

• ✅ 1 + 1
• ❌ 1+1 (This will be parsed as a text string or invalid token, not an addition)

This rule applies to all operators (+, -, =, ==, etc.) to ensure clear and unambiguous parsing as act allows the use of kebab-case keywords.

Caution

Operators have no precedence and are solved left to right.

So 1 - 2 + 3 * 4 + 5 will result in 13 instead of 16.

• 1 - 2 = -1
• -1 + 3 = 2
• 2 * 4 = 8
• 8 + 5 = 13

Please use parentheses to avoid this:
1 - 2 + (3 * 4) + 5 will be evaluated as 16.

Why? Because as this side project has grown out of control (and sanity), the parser was not meant for the stuff I was shoving into it, and I'm just too lazy to implement it.
Will the laziness ever be defeated? idk.

Note

All arithmetic and comparison operators can be used with dimensions if both operands are dimensions with the same dimension unit.

100px + 2px  // valid, returns 102px
100px > 2rem  // not valid, returns null

(#nonexistent-id *color: red) rescue (log: 'Unable to set the color of #nonexistent-id to red, the exception was:' $exception);

(
    #nonexistent-id *color: red;
) rescue (
    log: 'Unable to set the color of #nonexistent-id to red, the exception was:' $exception;
);

// Try to fetch data, fallback to default
$data: (fetch: '/api/data' then json!) rescue ['name': 'Default'];

// The $exception variable contains the caught exception
#risky-operation do
    // Some operation that might fail
    throw 'Something went wrong!';
end rescue (
    error: 'Caught exception:' $exception;
    // $exception contains the error message or Error object
);

// Validate and throw custom errors
$age: prompt: 'Enter your age:';
($age as number) < 18? throw: 'Must be 18 or older';

// Handle validation errors
(
    run validate_form;
) rescue (
    #error-message << `Error: {$exception}`;
    #error-message show!;
);

Note

Scopes are explained in the Data Scopes section.

local $a;
// Declares a variable $a with a null value.

local $b: 2;
// Declares a variable $b with a value of 2.

local $c: 2 + $b;
// Declares a variable $c with the result of the expression: a value of 4.

do
    log: $a; 
    // $a is found in the local scope, logs null.

    $a: 10;
    // Sets variable $a to 10.

    log: $a;
    // Logs 10.
end;

log: $a;
// Logs 10.

Note

Scopes are explained in the Data Scopes section.

global $a: 1;
// Declares a global variable $a with a value of 1.

Note

Scopes are explained in the Data Scopes section.

scoped $a: 1;

do
    log: $a;
    // Looks up for the $a variable; $a is found in the parent Scope, logs 1.

    scoped $a;
    // Declares a variable $a with a null value in this Scope.

    scoped $b: 2;
    // Declares a variable $b with a value of 2 in this Scope.

    $a: 10;
    // Sets scoped variable $a to 10.

    log: $a;
    // Finds $a variable in this Scope, logs 10.
end;

log: $a;
// Logs 1.

negative 5;    // Returns -5
-5;            // Same

$a: 10;
negative $a;   // Returns -10
-$a;           // Same

-(2 + 4);      // Returns -6

type 5;
// Returns 'number'

type #some-div;
// Returns 'element'

type [1, 2, 3];
// Returns 'array'

first .item *color: red;
// Selects the first element with class 'item' and sets its color to red.

$my_array: [1 2 3];
first $my_array; // Returns 1

last .item *color: blue;
// Selects the last element with class 'item' and sets its color to blue.

$my_array: [1 2 3];
last $my_array; // Returns 3

wat $some_variable;
// Logs detailed debug info about $some_variable

// Store an array
$numbers: [1 2 3];

// Spread as function arguments
log: ...$numbers;           // Logs 1, 2, 3 as separate arguments

// Spread into a new array
$more: [...$numbers 4 5 6]; // Creates [1, 2, 3, 4, 5, 6]

// Combine arrays
$a: [1 2];
$b: [3 4];
$combined: [...$a ...$b];   // Creates [1, 2, 3, 4]

if condition (
    // This Scope will be evaluated if the condition is true.
) else if other_condition (
    // This Scope will be evaluated if the first condition is false and this condition is true.
) else (
    // This Scope will be evaluated if all preceding conditions are false.
);

#some-element if :inner_html.includes: 'foo', (
    alert: 'The element has the word "foo" in its innerHTML';
) else if :inner_html.includes: 'bar', (
    alert: 'The element has the word "bar" in its innerHTML';
) else (
    alert: 'The element does not have the word "foo" or "bar" in its innerHTML';
);

Note

A note on act's simple but expressive syntax.

if, like the other keywords, is just one big expression with multiple Words and Scopes as lazy evaluated arguments.
act syntax is very simple, but it also allows for some expressive code.
With that said, let's get back to our scheduled programming...

<p> each (
    // The target inside this Scope will be set to each paragraph.
    << inner_html.to_upper_case!;
)

each $item in [1 2 3 4] (
    log: $item;
    $item is 3? log: 'Three is my favorite number!';
);

// Some object
$act_todo: [
    'Lexer': 'Slow but working'
    'Parser': 'Done'
    'Literal Values': 'Done'
    'Scope evaluation': 'Done'
    'Fix bugs': false
];

each $feature $status in $act_todo (
    if not $status (
        warn: `The feature {$feature} is not done yet.`;
    ) else if $status is_not 'Done' (
        log: `The feature {$feature} is done but may have some rough edges: {$status}.`;
    ) else (
        log: `The feature {$feature} is done.`;
    );
);

for $i to 10 ( // Starts at 0, ends at 10.
    log: $i;
);

for $i from 1 to 10 ( // Specifies a starting value.
    log: $i;
);

for $i from 1 to 10 step 2 ( // Specifies a step value that increments the variable on each iteration.
    log: $i;
);

for $i from 0 to <p>.length step 2 (
    // I will change the color of every odd <p> element.
    <p>[$i].*color: red;
);

$i: 0;
while $i < 10 (
    log: `The current index is {$i}.`;
    $i += 1;
);

loop (
    warn: 'This loop is running forever!';
);

// Loop with a break condition:
$count: 0;
loop (
    $count += 1;
    log: `Count: {$count}`;
    $count >= 5? break;
);

<div id="looper" act="loop (wait: 1s; log: 'Running...')">
    <button act@click="#looper kill act">Stop the loop</button>
</div>

def hello do
    log: 'Hello, world!';
end;

def greet $name (
    log: `Hello, {$name}!`;
);

run greet 'World';

// Variadic arguments (rest parameter)
def sum_all ...$numbers (
    $sum: 0;
    each $n in $numbers ( $sum += $n );
    log: $sum;
);

run sum_all 1 2 3 4;

<script type="text/act" act-block="my_block">
    log: 'Block executed';
</script>

<button act@click="run my_block">Run Block</button>

<script type="text/act" act-block="greet $name $greeting">
    log: `{$greeting}, {$name}!`;
</script>

<button act@click="run greet 'John' 'Hello'">Greet John</button>

<!-- Block defined in a sidebar, unrelated to the button -->
<aside id="shared-blocks">
    <script type="text/act" act-block="validate $value">
        log: `Validating: {$value}`;
    </script>
</aside>

<form>
    <button act@click="run validate from #shared-blocks 'hello'">Validate</button>
</form>

with #some-element (
    fade: out;
    // Fades out #some-element.

    #another-element hide!;  
    // Hides #another-element, as the explicit target of this sentence is #another-element and it will not fallback to the target of the "with" operation.
);

// It also works with other values that are not elements:
$some_array: [1 2 3];
with $some_array (
    push: 4;
    // Pushes value 4 to the end of $some_array.
);

$a_div: new <div>;
// Creates a new div HTML element.

$date: new Date;
// Creates a new JavaScript Date object.

$custom_date: new Date '2023-12-25';
// Creates a new Date object with arguments.

Warning

Be careful when adding event listeners. Act only stores one event listener per event name per element.
So while adding multiple event listeners that have the same name to an element works, removing an event listener with off will only remove the last one.

// Basic event
#some-element on click (
    log: 'Clicked!';
);

// With single-word options
#some-element on click target once (
    log: 'Clicked on:' me;
);

// Event delegation with matching
#some-list on click matching {.item} (
    log: 'Item clicked!';
    *color: red;
);

// Aliased event
#some-element on [myClick: click] (
    log: 'Aliased click!';
);

// Combined: alias + options + matching
#container on [itemClick: click] target matching {button.active} (
    log: 'Active button clicked:' :inner_text;
);

// With options object
#some-element on scroll [passive: true] (
    log: 'Scrolling...';
);

// With modifiers - only trigger on Ctrl+Click
#some-element on click [modifiers: ['ctrl']] (
    log: 'Ctrl+Click detected!';
);

// Combined: modifiers with single-word options
#some-element on click target [modifiers: ['ctrl' 'shift']] (
    log: 'Ctrl+Shift+Click on:' :tag_name;
);

#some-element off click;
#some-element off custom-event;

<div id="looper" act="loop (wait: 1s; log: 'Running...')">
    <button act@click="#looper kill act">Stop the loop</button>
</div>

<div id="looper" act="loop (transition: opacity to 0.2 in 1s; transition: opacity to 1 in 1s)">
    <button act@click="#looper kill act">Stop now (reverts the running transition)</button>
    <button act@click="#looper finish act">Stop after the current transition</button>
</div>

(wait: 2s; trigger: ready) &
wait_until ready;
log: 'The ready event fired!';

#dialog wait_until close;
log: 'The dialog was closed';

throw;
// Throws a generic ActError

throw 'Something went wrong!';
// Throws ActError with custom message

throw new Error 'Custom error';
// Throws a specific Error instance

$color: 'red';
case $color
when 'red' (
    log: 'The color is red!';
)
when 'blue' (
    log: 'The color is blue!';
)
else (
    log: `Unknown color: {$color}`;
);

// Using "like" for loose comparison (==)
$value: 1;
case $value
like '1' (
    log: 'Loosely matches the string "1"';
)
like true (
    log: 'Loosely matches true';
);

// case returns the result of the matched branch
$message: case $status
when 'ok' 'All good!'
when 'error' 'Something went wrong!'
else 'Unknown status';
log: $message;

debounce 500ms ( log: 'Debounced' );

lock;
lock click;
lock scroll false;

is_locked? log: 'Locked';

$i: 0;
$result: while $i < 10 (
    $i += 1;
    if $i == 5 (
        break 'Done';
    );
);

$i: 0;
loop (
    $i += 1;
    $i % 2 is 0? continue;
    $i >= 20? break;
    log: $i;
    // Logs odd numbers 1, 3, 5, ..., 19
);

// ...
log: 'Looping forever!';
repeat;

// ...
$name: prompt: 'What is your name?';
$age: prompt: 'How old are you?';
if $name == 'John' and $age < 18 (
    restart;  // Goes back to the top!
);
// ...

$username == 'John' ? stop 'John found';
// If the username is John, the execution of the current scope will be stopped and the value 'John found' will be returned.

// ...
$name: (#username-field :value.to_upper_case!);
log: 'Hello {$name}!';
if $name is 'JOHN' and #age-field.value as number < 18 (
    halt;
);
// ...

$validate: -> $name (
    $name == 'John'? return 'John found';
    // ...
    return 'John not found';
);

#some-element transition: transform from 'scale(1)' to 'scale(0.75)' in 0.5s 
background-color to white in 1s color to black in 1s;

#some-element transition: background-color from red to black in 250ms using ease-in-out after 10s &
// This transition will take 10 seconds + 250 milliseconds to complete, but as the sentence is asynchronous it will not wait for the transition to finish before continuing.

#some-element transition: border-color to #ff0 in 500ms width to (*width + 50px) in 750ms using linear;

#some-element move_to: #new-parent;
#some-element move_to: #new-parent afterbegin;
{< p} move_to: first <article> append;

$copy: #some-element.clone!;
#container append: #template.clone!;

#some-element prepend: 'Hello';
#some-element prepend: '<p>First paragraph</p>';
#some-element prepend: new <div>;

#some-element append: 'World';
#some-element append: '<p>Last paragraph</p>';
#some-element append: new <div>;

#some-element set_html: '<p>New content</p>';

#some-element set_outer_html: '<section>Replacement</section>';

#some-element remove!;                        // Removes the element from DOM
#some-element remove: .active;                // Removes the 'active' class
#some-element remove: @disabled;              // Removes the 'disabled' attribute
#some-element remove: .active .highlighted;   // Removes multiple classes at once

#some-element has: .active;
    // Element has class 'active'

#some-element has: @disabled;
    // Element has attribute 'disabled'

#some-element toggle!;
// Toggles visibility

#some-element toggle: .active;
// Toggles the 'active' class

#some-element toggle: @disabled;
// Toggles the 'disabled' attribute

#some-element toggle: .selected true;
// Forces the 'selected' class to be added

#some-element add: .active;
// Adds the 'active' class

#some-element add: @data-enabled;
// Adds the 'data-enabled' attribute with an empty value

#some-element add: .active @data-enabled;
// Adds both in one call

#some-element is_in_view! ? log: 'Visible';
#some-element is_in_view: true;
// Returns 'partially' if any part is visible

#some-element.next! *color: red;
#some-element.next: .item;

#some-element previous! *color: blue;
#some-element previous: .item;

#some-element parent! *border: 1px solid black;

#some-element matches: .active ? log: 'It is active';
#some-element matches: {div.container > p};

#some-element take: .active;
// Takes 'active' class from siblings (parent defaults to parentNode)

#some-element take: @disabled;
// Takes 'disabled' attribute from siblings

#some-element take: .selected #my-list;
// Takes 'selected' class from elements inside #my-list

#some-element fade: out 1s;
#some-element fade: in 500ms ease-in-out;
#some-element fade: out;   // defaults to 250ms linear

last .item move_to: #container;
last .moved-item move_to: #container prepend;

#my-element trigger: click;
#my-element trigger: data_updated true [id: 123, status: complete];
#my-element trigger: notification false [message: 'Hello!'];

js trigger: app_ready;              // on window
document trigger: theme_changed true [theme: 'dark'];

$nums: [1 2 3];
$doubled: $nums.map: -> $x ($x * 2);

$nums: [1 2 3 4];
$evens: $nums.filter: -> $x ($x % 2 == 0);

$nums: [1 2 3];
$nums.for_each: -> $x (log: $x);

$users: [[name: 'Alice' id: 1] [name: 'Bob' id: 2]];
$user: $users.find: -> $u ($u.id == 2);

$nums: [10 20 30];
$idx: $nums.find_index: -> $x ($x > 15); // Returns 1

$nums: [1 2 3];
$has_even: $nums.some: -> $x ($x % 2 == 0); // Returns true

$nums: [2 4 6];
$all_even: $nums.every: -> $x ($x % 2 == 0); // Returns true

'hello world'.after: ' '; // Returns 'world'

'hello world'.before: ' '; // Returns 'hello'

'hello [world]'.between: '[' ']'; // Returns 'world'

'hello'.capitalize!; // Returns 'Hello'

wait: 1s;
wait: 150ms;
wait: 500; // integers are treated as miliseconds

warn: 'Something is wrong';

$ms: time_to_ms: 1s; // 1000

#btn is_running! ? log: 'Running';
#btn is_running: click;

// Alert
alert: 'Hello world!';

// Confirm
confirm: 'Are you sure?' ? log: 'User confirmed';

// Prompt
$name: prompt: 'What is your name?';

// LocalStorage
local_storage.set_item: 'theme' 'dark';
$theme: local_storage.get_item: 'theme';

log: window.inner_width;
log: js.inner_width;

[1 2 3] each ( log: me );

$result: undefined;
log: undefined;

$invalid: NaN;
0 / 0 == NaN; // false (NaN is never equal to itself)

<button act@click="fade: out">Fade me out!</button>

<button>
    <script type="text/act" act@click>
        fade: out;
    </script>
    Fade me out!
</button>

log: $event.type;           // e.g. 'click'
log: $event.target;         // the element that was clicked
log: $event.detail;         // custom data for CustomEvents

<button act@click,mouseleave="fade: out">Fade me out!</button>

<button act@mouseleave="*color: gray" act@click="*color: green">
    <script type="text/act" act@keyup>
        *color: red;
    </script>
    <script type="text/act" act@mouseenter>
        *color: blue;
    </script>
    Multi-colored button
</button>

<p act@inview="fade: in; *color: red;" act@offview="*color: blue; fade: out;">
    I fade in when I'm in the viewport and fade out when I'm out of the viewport.
</p>

<ul id="items">
    <script type="text/act">
        on inview matching <li> (add: .seen);
        on offview matching <li> (remove: .seen);
    </script>
    <li>Item 1</li>
    <li>Item 2</li>
    <li>Item 3</li>
</ul>

<div act="log: 'Element initialized'">
    <!-- This code runs when Act starts -->
</div>

<main act="run init_app">
    <script type="text/act" act-block="init_app">
        // Initialization logic here
        log: 'App initialized';
    </script>
</main>

<!-- Trigger only on Enter key -->
<input act@keyup.enter="submit!">

<!-- Trigger on Shift + Enter -->
<textarea act@keyup.shift.enter="new_line!"></textarea>

<!-- Trigger on Ctrl + S -->
<div act@keydown.ctrl.s="save!">Save</div>

<!-- Shift-click to delete -->
<button act@click.shift="delete!">Delete (Shift-Click)</button>

<button id="handlers" act@click#my_handler="log: 'Handler 1'" act@click#another_handler="log: 'Handler 2'">
    Click me - both handlers will fire
</button>

<button act@click="#handlers off my_handler">
    Remove only the first handler
</button>

<div id="animated" act@act#animation="fade: out 500ms; fade: in 500ms; repeat;">
    <button act@click="#animated kill animation">Stop animation</button>
</div>

Note

HTML lowercases attribute names, so aliases are effectively case-insensitive: act@click#saveForm registers saveform, and kill saveForm will not find it. Stick to lowercase or snake_case alias names.

<!-- every htmx event needs brackets -->
<div act@[htmx:before:request]="add: .loading"></div>
<div act@[htmx:after:swap]="log: 'swapped'"></div>

<!-- a custom event containing a dot -->
<div act@[cart.updated]="run refresh_cart"></div>

<div act@[htmx:after:swap]#[after.swapping]:once="log: 'once'"></div>
<!-- event: htmx:after:swap   alias: after.swapping   option: once -->

<div act@my:custom:event="..."></div>
<!-- 💣 act: Unknown event option ":custom" in "act@my:custom:event".
     If it is part of a name, wrap the name in brackets: act@[my:custom] -->

Warning

Attribute names are lowercased by HTML, so an event whose name contains capitals, such as htmx's htmx:before:viewTransition, cannot be bound from an attribute at all. Use the on keyword with a quoted string, which preserves case:

<script type="text/act">
    on 'htmx:before:viewTransition' ( log: 'transitioning' );
</script>

<div id="my-element" act@my_custom_event="log: 'Custom event received!' $event.detail">
    Waiting for custom event...
</div>

document.querySelector('#my-element').dispatchEvent(
    new CustomEvent('my_custom_event', { detail: { message: 'Hello!' } })
);

<button act@click="#my-element trigger: my_custom_event true [message: 'Hello from Act!']">
    Trigger from Act
</button>

document.addEventListener('actready', (e) => {
    console.log('Act ready. Bound nodes:', e.detail.bindedNodes);
});

document.addEventListener('actbind', (e) => {
    console.log('Element bound:', e.detail.element, e.detail.binding);
});

document.addEventListener('actstart', (e) => {
    e.target.setAttribute('aria-busy', 'true');
});

document.addEventListener('actend', (e) => {
    e.target.removeAttribute('aria-busy');
});

document.addEventListener('acterror', (e) => {
    console.error('Act error:', e.detail.error);
});

document.addEventListener('actscriptloaded', (e) => {
    console.log('External act script loaded:', e.detail.element);
});

Act.extend(plugin);         // single plugin
Act.extend(a).extend(b);    // chained

// Object form
Act.extend({
    name: 'my-plugin',   // optional, useful for debugging

    install(Act) {
        // runs before Act.start()
    },

    ready(Act) {
        // runs after Act.start()
    },
});

// Function shorthand (treated as install)
Act.extend(function (Act) {
    Act.Library.Element.pinkify = function () {
        this.style.backgroundColor = 'pink';
    };
});

Act.extend({
    install(Act) {
        // configure
        // Enable sanitization
        Act.config.sanitize = true;
        // sanitizer receives (element, html); return the clean string, or null to skip insertion
        Act.config.sanitizer = (element, html) => DOMPurify.sanitize(html);

        // add a library method
        Act.Library.Element.shine = function () {
            this.style.boxShadow = '0 0 12px gold';
        };

        // add a keyword
        Act.Library.keywords.unless = async function (ctx, target, opts, args) {
            const [condition, body] = args;
            if (!(await ctx.asValueOf(condition, target)))
                return await ctx.solve(body, target, opts);
        };

        // add a prefix
        Act.Library.prefixes.maybe = async function (ctx, target, opts, value) {
            try { return await ctx.asValueOf(value, target); }
            catch { return undefined; }
        };
    },
});

Act.extend({
    ready(Act) {
        console.log('Act is ready. Extensions:', Act.extensions.length);
    },
});

// Loaded lazily, long after DOMContentLoaded
const { myPlugin } = await import('./my-plugin.js');
Act.extend(myPlugin);
// → install() fires right now
// → ready() fires right now
// Any new keywords/methods are available for future Act.init() calls

console.log(Act.extensions.map(e => e.name));
// ['act-ext', 'my-plugin', ...]

Important

Act.Library.object is not limited to plain objects. Step 3 selects the bucket by typeof target, and typeof reports 'object' for Elements, Arrays, NodeLists, window and document too. So a method registered there is reachable from every object target that steps 1 and 2 did not already resolve. Put a method there only if it makes sense for all of them, or guard it and throw. trigger is the built-in example: it lives in object so it can reach window and document, and throws when the target cannot dispatch events.

Buckets also exist for the remaining typeof results (boolean, function, bigint, symbol and undefined) and are empty by default.

Act.extend({
    install(Act) {
        // Global method, available on any target
        Act.Library.globals.double_log = function (...args) {
            const values = Act.unwrapAll(args);
            console.log(...values);
            console.log(...values);
        };

        // Element method, available when target is an Element
        Act.Library.Element.pinkify = function () {
            this.style.backgroundColor = 'pink';
            this.style.color = 'black';
        };

        // String method, available when target is a string
        Act.Library.string.shout = function () {
            return this.toUpperCase() + '!!!';
        };
    },
});

<button act@click="double_log: 'hi'; pinkify!;">Click me!</button>
<p act@click="log: 'hello'.shout!;">Hover me!</p>

Act.extend({
    install(Act) {
        // `unless condition body`: inverse of `if`
        Act.Library.keywords.unless = async function (ctx, target, opts, args) {
            const [condition, body] = args;
            if (!(await ctx.asValueOf(condition, target)))
                return await ctx.solve(body, target, opts);
        };

        // `wait_more duration`: waits 10x longer than `wait`
        Act.Library.keywords.wait_more = async function (ctx, target, opts, args) {
            const { wait, time_to_ms } = Act.Library.globals;
            if (!args[0]) return await wait.call(target, '60s');
            const solved = await ctx.solve(args[0], target, opts);
            return await wait.call(target, time_to_ms.call(target, Act.unwrap(solved) * 10));
        };
    },
});

<div act@click="unless $disabled (log: 'fired!')"></div>

Act.extend({
    install(Act) {
        // `maybe value`: returns undefined instead of throwing
        Act.Library.prefixes.maybe = async function (ctx, target, opts, value) {
            try { return await ctx.asValueOf(value, target); }
            catch { return undefined; }
        };

        // `double value`: multiplies a number by 2
        Act.Library.prefixes.double = async function (ctx, target, opts, value) {
            return Act.unwrap(await ctx.asValueOf(value, target)) * 2;
        };
    },
});

<div act@click="log: maybe $risky-prop; log: double 21;"></div>

Act.extend({
    install(Act) {
        // `viewport_width`: returns window.innerWidth
        Act.Library.words.viewport_width = () => window.innerWidth;

        // `is_mobile`: returns a boolean
        Act.Library.words.is_mobile = () => window.innerWidth < 768;
    },
});

<div act="log: viewport_width; is_mobile? hide!"></div>

// Unwrap a Result to get its raw JS value
const value = Act.unwrap(result);

// Unwrap all values in an array
const values = Act.unwrapAll([result1, result2]);

// Solve a solvable (use inside keyword and prefix operations)
const result = await ctx.solve(solvable, target, opts);

// Solve and immediately unwrap
const value = Act.unwrap(await ctx.solve(solvable, target, opts));

Act.abortable({
    perform: done => { /* perform the operation, call done() when finished */ },
    abort:   ()   => { /* cleanup code that runs only when killed */ },
})

Note

abort only runs on kill. A graceful finish lets the operation complete normally and never triggers it.

Act.extend({
    install(Act) {
        Act.Library.Element.highlight = function (duration) {
            const original = this.style.backgroundColor;
            this.style.backgroundColor = 'yellow';
            let t;
            return Act.abortable({
                perform: done => {
                    t = setTimeout(() => { 
                        this.style.backgroundColor = original; 
                        done(); 
                    }, Act.unwrap(duration));
                },
                abort: () => { 
                    clearTimeout(t); 
                    this.style.backgroundColor = original; 
                },
            });
        };
    },
});

<p id="msg" act@click="highlight: 3s;">Click to highlight for 3 seconds</p>
<button act@click="#msg kill click">Cancel highlight</button>

Act.extend({
    install(Act) {
        Act.Library.Element.typewrite = function (text, speed) {
            text  = Act.unwrap(text);
            speed = Act.unwrap(speed) ?? 50;
            let i = 0, t;
            return Act.abortable({
                perform: done => {
                    const tick = () => {
                        this.textContent += text[i++];
                        if (i < text.length) t = setTimeout(tick, speed);
                        else done();
                    };
                    t = setTimeout(tick, speed);
                },
                abort: () => { clearTimeout(t); this.textContent = text; },
            });
        };
    },
});

<p id="msg" act="typewrite: 'Hello, world!' 80;">
<button act@click="#msg kill act">Skip</button>

<script src="act.js"></script>
<script src="htmx.js"></script>
<script src="act-htmx.js"></script>

<!DOCTYPE html>
<html>
<head>
    <script src="act.js"></script>
    <script src="htmx.js"></script>
    <script src="act-htmx.js"></script>
</head>
<body>
    <button hx-get="/new-content" hx-target="#container">
        Load Content
    </button>
    
    <div id="container"></div>
</body>
</html>

<!-- Server response from /new-content -->
<div>
    <button act@click="alert: 'I work!'">Click me!</button>
    <p act@mouseover="*color: red">Hover me!</p>
</div>

{
  "compilerOptions": {
    "include": ["act.d.ts"]
  }
}

Act.extend({
    install(Act) {
        Act.config.sanitize = true;
        // Receives (element, html). Return the sanitized string, or null to skip insertion.
        Act.config.sanitizer = (element, html) => DOMPurify.sanitize(html);
    },
});

Note

Sanitization only applies to HTML string insertion. Element and DocumentFragment values bypass the hook and are inserted directly.