--- url: /reference/items/Action/js-api.md --- # JS API ## Options ### `on` * Type: `string` * Default: `'click'` * Format: `[....]` The event that triggers the [effect callback](#effect) on the defined [targets](#target). Modifiers configure how the event is listened to. Available modifiers are: * `prevent` to call the `event.preventDefault()` in the event handler * `stop` to call the `event.stopPropagation()` in the event handler * `passive` to register the handler with passive mode enabled * `once` to trigger the handler only once * `capture` to register the handle in capture mode * `debounce` to debounce the event handler with a 100ms delay by default * `debounce` to debounce the event handler with a custom delay in milliseconds (e.g., `debounce300`) Modifiers can be chained with a `.` as separator: ```html {3} ``` ### `target` * Type: `string` * Available formats: * `Name` * `Name OtherName` * `Name(.selector)` * `Name(.selector) OtherName([value="other-selector"])` Defines the components used as targets to the [effect callback](#effect). Multiple components can be defined by using a single space as delimiter. ::: info Name definition The `Action` component will use the `name` property defined in the static `config` object of each class to resolve components on the page. ```js {3} class Foo extends Base { static config = { name: 'Foo', }; } ``` ::: #### No target By not defining the `target` option, the default target will be the current `Action` instance. The following will toggle the `clicked` class on the ` ``` #### Single target The following configuration will use all `Foo` components as targets, the effect callback will be triggered for each and every one of them. ```html {3} ``` #### Multiple targets ```html {3} ``` #### Reduce the list of target with a selector In the following example, the effect callback will only be triggered on the `Foo` component with the `foo` id. ```html {3,7}
...
...
``` ### `effect` * Type: `string` * Required Defines a small piece of JavaScript executed in the context of the current target. The following variables are available: * `this` (`HTMLElement`): the current element * `ctx` (`Record`): the current targeted component in an object with a uniq key being its name set in the static `config.name` property and the value being the component instance * `event` (`Event`): the event that triggered the action * `target` (`Base`): a direct reference to the current targeted component * `action` (`Base`): a direct reference to the current action component * `$el` (`HTMLElement`): a direct reference to the targeted element * `Action` (`Base`): a direct reference to the current action component * `` (`Base`): a direct reference to the `Name` component mounted on the current element #### Simple effect vs callback effect The effect can also define an arrow function which will be executed as well. The following examples are similar: ```html {3,9} ``` #### Accessing the current element Use `this` to access the current element: ```html {3-4} ``` #### Accessing the target element Use `$el` to access the current element: ```html {3-4}
...
``` #### Accessing the current instances mounted on the current element Use the name of the component mounted on the current element to get access to its instance. ```html {3} ``` By default, the `Action` variabl will always refer to the current `Action` instance of the current element. The following example will log `true` when the button is clicked: ```html {3} ``` #### Advanced usage with destructuration This can be useful to destructure the first `ctx` parameter and make a direct reference to the targeted component's name when multiple target are defined: ```html {3,4} ``` ::: warning Advanced pattern The pattern described above with multiple components as targets is an advanced pattern that should be used with care, as it adds complexity to the DOM that might not be necessary. ::: ### `on:[.]` * Type: `string` * Format: `[[()] -> ]` Combines the [`on`](#on), [`target`](#target) and [`effect`](#effect) options into a single attribute. Attaches multiple events to a single `Action` component. ```html {3} ``` ::: warning Virtual option This is a virtual option, meaning that it can be used in HTML but will not be present in the `$options` property of the component in JavaScript. :::