A collection of magic properties and helper functions for use with Alpine.
npm install alpine-magic-helpersA collection of magic properties and helper functions for use with Alpine.js
Adds the following magic helpers to use with Alpine JS.
| Magic Helpers | Description |
| --- | --- |
| $component/$parent | Natively access and update data from other components or the parent component. |
| $fetch/$get/$post | Using Axios, fetch JSON from an external source. |
| $interval | Run a function every n milliseconds. Optionally start and stop the timer. |
| $range | Iterate over a range of values. |
| $refresh | Manually refresh a component. |
| $screen | Detect if the current browser width is equal or greater than a given breakpoint. |
| $scroll | Scroll the page vertically to a specific position. |
| $truncate | Limit a text string to a specific number of characters or words. |
| $undo | Track and undo state changes inside your component. |
Adds the following custom directives to use with Alpine JS.
| Custom Directives | Description |
| --- | --- |
| x-unsafe-html | like x-html but allowing new javascript scripts to run. |
More to come!
š If you have ideas for more magic helpers or custom directives, please open a discussion or join us on the AlpineJS Discord
Known issues
* Using $component/$parent in x-init
* Using Magic Helpers with Livewire
Include the following
Or you can use the specific magic helpers you need:
`html`
---
If you wish to create your own bundle:
`bash`
npm install alpine-magic-helpers --save
Then add the following to your script:
`javascript`
import 'alpine-magic-helpers'
import 'alpinejs'
Or you can import the specific magic helpers you need like so:
`javascript`
import 'alpine-magic-helpers/dist/component'
import 'alpine-magic-helpers/dist/fetch'
import 'alpinejs'
---
without the defer attribute.---
$3
Example:Arguably more useful, this also adds a
$parent magic helper to access parent data
`html
`
DemoYou may watch other components, but you must give them each an id using the 'id' attribute or
if you need more flexibility:
`html
x-text="$component('yellowSquare').color"
:class="text-${$parent.color}-700">
`#### :warning: Using
/$parent in x-init
html
`
When a component is initialised, the observed component may not be ready yet due to the way Alpine starts up. This is always true for and it occurs for $component when the observer is placed before the observed component in the page structure.
Previous versions were using a hack to evaluate the missing x-data on the fly but that strategy wasn't allowing to use nested magic properties and it was not syncronising properly in some edge cases.
The magic helper since version 1.0 defers the resolution of those properties (resolving temporary to empty strings/noop functions) until the observed component is ready and then refreshes the component: this happens in a few milliseconds and it's not noticable by the final users but refreshing a component won't rerun x-init with the correct values.
If developers need to use the magic property inside x-init, they'll need to manually postpone the execution of x-init for one tick either using the Alpine native $nextTick or a setTimeout with no duration (See examples above).---
$3
Example:
`html
x-init="$fetch(url).then(data => console.log(data))">
Demo> As a shortcut, you can optionally use
or $post(url, data) to conveniently send a GET or POST request with params or data as the second argument.Optionally pass in an Axios options object
If you need more control, you may pass in an object to customize the request See all options.
Example:
`html
x-init="$fetch({ url: url, method: 'post' }).then(({ data }) => console.log(data))">
> Note that this will return the entire response object, whereas by default will only return the data---
$3
Example:
`html
timer: 500,
functionToRun: function() {
console.log('Hello console')
}
}"
x-init="$interval(functionToRun, timer)">
DemoOptionally pass in options
By default,
will run your function every nth millisecond when browser provides an animation frame (via requestAnimationFrame). This means that the function will not run if the browser tab is not visible. Optionally, you may pass in the following options as the second parameter:
| Property | Description |
| --- | --- |
| timer | Timer in milliseconds. |
| delay | Delay the first run. N.B. The first run is also delayed by the timer time. |
| forceInterval | Ignore the browser animation request mechanism. Default is false |> ā ļø We also add a hidden property
autoIntervalTest that will clear/stop the timer if set to false, and start the timer if then set to true.Example:
`html
timer: 500,
autoIntervalTest: true, // optional to start/stop the timer
funtionToRun: function() {
console.log('Hi again!')
}
}"
x-init="$interval(funtionToRun, { timer: 1000, delay: 5000, forceInterval: true })">
x-text="autoIntervalTest ? 'pause' : 'play'">
Demo---
$3
Example:The
helper mostly mimics implementations found in other languages $range(start, stop, step = 1)
html
...
`
Demo> N.B: You may use
which will compute to [1...10]---
$3
Example:
html
`
Demo---
$3
Example:The
helper detects if the current browser width is equal or greater than a given breakpoint and returns true or false based on the result.`html
This will be visible if the window width is equal or greater than 1024px.
`By default the
helper uses the following endpoint borrowed by Tailwind CSS:
- xs: 0px
- sm: 640px
- md: 768px
- lg: 1024px
- xl: 1280px
- 2xl: 1536px> ā ļø NOTE: A single breakpoint is only going to tell you if the browser width is equal or greater than the given breakpoint. If you want to restrict the check to a specific range, you will need to negate the next endpoint as:
`html
This will be visible if screen width is equal or greater than 768px but smaller then 1024px.
`Custom breakpoints
You can pass a numeric value to use an ad-hoc breakpoint.
html
This will be visible if screen width is equal or greater than 999px.
`You can also override the default breakpoints including the following
And using those breakpoints in your page.
html
This will be visible if screen width is equal or greater than 769px.
`---
$3
Example:
html
...
`
DemoAlternatively, you can pass a css selector to scroll to an element at any position.
html
` also supports integers to scroll to a specific point of the page.
`html
`
Demo (same as above) optionally supports a second parameter where it's possible to define the behavior mode, auto|smooth (default smooth):
`html
...
...
...
`
With offset:
html
...
...
...
`
With both:
html
...
...
...
`
Demo (same as above)---
$3
Example:
html
x-text="$truncate(string, characters)"
@click="characters = undefined">
You may also pass a third argument to change the string that will be appended to the end:
html
x-text="$truncate(string, characters, ' (...)')">
DemoOptionally pass in options
By default,
will return take characters as a parameter. Instead you can pass in an object and trim by words. You may also update the ellipsis.Example:
`html
x-text="$truncate(string, { words: words, ellipsis: ' ...read more' })"
@click="count = 0">
`
Demo (same as above)
> Behind the scenes, for words, this uses which does not define a word in all languages.---
$3
Example:
`html
`
DemoThe
helper actually involves three helpers in one. First, add the $track() helper to the x-init directive to start tracking the component state. Next, add a button to $undo() changes as needed. And finally, you can access whether changes have occurred by using $history.length.Optionally pass in options
By default,
$undo will track all properties. Optionally you may limit the properties by passing in a string with the property name, or an array of property names.Example:
`html
`
> Use to track multiple properties---
$3
Example:
`html
``> :warning: Only use on trusted content. :warning:
>
> Dynamically rendering HTML from third parties can easily lead to XSS vulnerabilities.
---
Copyright (c) 2020 Alpine Collective
Licensed under the MIT license, see LICENSE.md for details.