https://github.com/alpine-collective/alpine-magic-helpers

Skip to content
 
Sign up

  * Why GitHub?
    Features -
      + Mobile -
      + Actions -
      + Codespaces -
      + Packages -
      + Security -
      + Code review -
      + Project management -
      + Integrations -
      + GitHub Sponsors -
      + Customer stories -
      + Security -
  * Team
  * Enterprise
  * Explore
      + Explore GitHub -

    Learn & contribute

      + Topics -
      + Collections -
      + Trending -
      + Learning Lab -
      + Open source guides -

    Connect with others

      + The ReadME Project -
      + Events -
      + Community forum -
      + GitHub Education -
      + GitHub Stars program -
  * Marketplace
  * Pricing
    Plans -
      + Compare plans -
      + Contact Sales -
      + Nonprofit -
      + Education -

[                    ] [search-key]

  *  
    #
    In this repository All GitHub |
    Jump to |

  * No suggested jump to results

  *  
    #
    In this repository All GitHub |
    Jump to |
  *  
    #
    In this organization All GitHub |
    Jump to |
  *  
    #
    In this repository All GitHub |
    Jump to |

Sign in Sign up
{{ message }}

alpine-collective / alpine-magic-helpers

generated from KevinBatdorf/alpine-plugin-template

  * Sponsor

    Sponsor alpine-collective/alpine-magic-helpers

  * Watch 6
  * Star 280
  * Fork 8

A collection of magic properties and helper functions for use with
Alpine.js

npmjs.com/alpine-magic-helpers
MIT License
280 stars 8 forks
Star
Watch

  * Code
  * Issues 1
  * Pull requests 0
  * Discussions
  * Actions
  * Projects 1
  * Security
  * Insights

More

  * Code
  * Issues
  * Pull requests
  * Discussions
  * Actions
  * Projects
  * Security
  * Insights

master
5 branches 17 tags
Go to file Code
 
Clone
HTTPS GitHub CLI
[https://github.com/a]

Use Git or checkout with SVN using the web URL.

[gh repo clone alpine]

Work fast with our official CLI. Learn more.

  * Open with GitHub Desktop
  * Download ZIP

Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Go back

Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Go back

Launching Xcode

If nothing happens, download Xcode and try again.

Go back

Launching Visual Studio

If nothing happens, download the GitHub extension for Visual Studio
and try again.

Go back

Latest commit

KevinBatdorf@users.noreply.github.com
KevinBatdorf@users.noreply.github.com Update version in README
...
7a6beba Feb 13, 2021
Update version in README
7a6beba

Git stats

  * 91 commits

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
.github
remove pr approval requirement (#80)
Feb 10, 2021
dist
Feature/magic properties in component (#82)
Feb 10, 2021
examples
Feature/magic properties in component (#82)
Feb 10, 2021
src
Feature/magic properties in component (#82)
Feb 10, 2021
tests
Feature/magic properties in component (#82)
Feb 10, 2021
.editorconfig
Initial commit
Aug 16, 2020
.eslintignore
refactor (#7)
Sep 30, 2020
.eslintrc.js
refactor (#7)
Sep 30, 2020
.gitignore
Initial commit
Aug 16, 2020
CHANGELOG.md
Feature/magic properties in component (#82)
Feb 10, 2021
LICENSE.md
refactor (#7)
Sep 30, 2020
README.md
Update version in README
Feb 13, 2021
babel.config.js
refactor (#7)
Sep 30, 2020
jest.config.js
refactor (#7)
Sep 30, 2020
package-lock.json
1.0.0
Feb 13, 2021
package.json
1.0.0
Feb 13, 2021
rollup.config.js
feature: add new $refresh helper (#75)
Feb 5, 2021
View code

README.md

 Magic Helpers

A collection of magic properties and helper functions for use with
Alpine.js

GitHub tag (latest by date) [6874747073]

 About

Adds the following magic helpers to use with Alpine JS. More to come!

Magic Helpers                       Description
$component/   Natively access and update data from other components
$parent       or the parent component.
$fetch        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.

 If you have ideas for more magic helpers, please open a discussion
or join us on the AlpineJS Discord

 Installation

Include the following <script> tag in the <head> of your document
(before Alpine):

<script src="https://cdn.jsdelivr.net/gh/alpine-collective/alpine-magic-helpers@1.0.x/dist/index.min.js"></script>

Or you can use the specific magic helpers you need:

<script src="https://cdn.jsdelivr.net/gh/alpine-collective/alpine-magic-helpers@1.0.x/dist/component.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/alpine-collective/alpine-magic-helpers@1.0.x/dist/fetch.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/alpine-collective/alpine-magic-helpers@1.0.x/dist/interval.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/alpine-collective/alpine-magic-helpers@1.0.x/dist/range.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/alpine-collective/alpine-magic-helpers@1.0.x/dist/refresh.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/alpine-collective/alpine-magic-helpers@1.0.x/dist/screen.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/alpine-collective/alpine-magic-helpers@1.0.x/dist/scroll.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/alpine-collective/alpine-magic-helpers@1.0.x/dist/truncate.min.js"></script>

---------------------------------------------------------------------

 Manual

If you wish to create your own bundle:

npm install alpine-magic-helpers --save

Then add the following to your script:

import 'alpine-magic-helpers'
import 'alpinejs'

Or you can import the specific magic helpers you need like so:

import 'alpine-magic-helpers/dist/component'
import 'alpine-magic-helpers/dist/fetch'
import 'alpinejs'

 $component

Example:

Arguably more useful, this also adds a $parent magic helper to access
parent data

<div x-data="{ color: 'blue' }">
    <p x-data x-text="$parent.color"></p>
    <!-- The text will say blue -->
</div>

Demo

You may watch other components, but you must give them each an id
using the 'id' attribute or x-id if you need more flexibility:

<div x-data="{ color: 'blue' }">
    <p
        x-data
        x-text="$component('yellowSquare').color"
        :class="`text-${$parent.color}-700`">
        <!-- This text will have blue background color and the text will say yellow -->
    </p>
</div>

<div x-id="yellowSquare" x-data="{ color: 'yellow' }"></div>

 $fetch

Example:

<div x-data="{ url: 'https://jsonplaceholder.typicode.com/todos/1' }"
    x-init="$fetch(url).then(data => console.log(data))">
    <!-- After init, data will be logged to the console -->
</div>

Demo

Optionally pass in an options object

By default, $fetch will return the JSON data object. However, because
we are using Axios behind the scenes, you may pass in an object to
customize the request See all options.

Example:

<div x-data="{ url: 'https://jsonplaceholder.typicode.com/todos/1' }"
    x-init="$fetch({ url: url, method: 'post' }).then(({ data }) => console.log(data))">
</div>

    Note that this will return the entire response object, whereas by
    default $fetch will only return the data

---------------------------------------------------------------------

 $interval

Example:

<div
    x-data="{
        timer: 500,
        functionToRun: function() {
            console.log('Hello console')
        }
    }"
    x-init="$interval(functionToRun, timer)">
</div>

Demo

Optionally pass in options

By default, $interval 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:

<div
    x-data="{
        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 })">
    <button
        @click="autoIntervalTest = !autoIntervalTest"
        x-text="autoIntervalTest ? 'pause' : 'play'"></button>
</div>

Demo

---------------------------------------------------------------------

 $range

Example:

The $range helper mostly mimics implementations found in other
languages $range(start, stop, step = 1)

<div x-data>
    <template x-for="item in $range(1, 5)">
        ...
    </template>
</div>
<!-- This will output 5 iterations [1, 2, 3, 4, 5], modelled after PHP's implimentation of range() -->

Demo

    N.B: You may use $range(10) which will compute to [1...10]

---------------------------------------------------------------------

 $refresh

Example:

<div x-data>
    <button @click="$refresh()">Refresh <code>Date.now()</code></button>
    <span x-text="Date.now()"></span>
</div>

Demo

---------------------------------------------------------------------

 $screen

Example:

The $screen helper detects if the current browser width is equal or
greater than a given breakpoint and returns true or false based on
the result.

<div x-data>
    <span x-show="$screen('lg')">This will be visible if the window width is equal or greater than 1024px.</span>
</div>

By default the $screen 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:

<div x-data>
    <span x-show="$screen('md') && !$screen('lg')">This will be visible if screen width is equal or greater than 768px but smaller then 1024px.</span>
</div>

Custom breakpoints

You can pass a numeric value to use an ad-hoc breakpoint.

<div x-data>
    <span x-show="$screen(999)">This will be visible if screen width is equal or greater than 999px.</span>
</div>

You can also override the default breakpoints including the following
<script> tag in the <head> of your document

<!-- this example uses Bulma's breakpoints. -->
<script>
    window.AlpineMagicHelpersConfig = {
        breakpoints: {
            mobile: 0,
            tablet: 769,
            desktop: 1024,
            widescreen: 1216,
            fullhd: 1408
        }
    }
</script>

And using those breakpoints in your page.

<div x-data>
    <span x-show="$screen('tablet')">This will be visible if screen width is equal or greater than 769px.</span>
</div>

Demo

---------------------------------------------------------------------

 $scroll

Example:

<div x-data>
    <div x-ref="foo">
        ...
    </div>
    <button x-on:click="$scroll($refs.foo)">Scroll to foo</scroll>
</div>

Demo

Alternatively, you can pass a css selector to scroll to an element at
any position.

<div id="foo">
</div>
<div x-data>
    <button x-on:click="$scroll('#foo')">Scroll to #foo</scroll>
</div>

$scroll also supports integers to scroll to a specific point of the
page.

<button x-data x-on:click="$scroll(0)">Scroll to top</scroll>

Demo (same as above)

$scroll optionally supports a second parameter where it's possible to
define the behavior mode, auto|smooth (default smooth):

<div x-data>
    <div x-ref="foo">
        ...
    </div>
    <button x-on:click="$scroll($refs.foo, {behavior: auto})">Jump to foo</scroll>
</div>
...
<div id="foo">
</div>
<div x-data>
    <button x-on:click="$scroll('#foo, {behavior: auto}')">Jump to #foo</scroll>
</div>
...
<button x-data x-on:click="$scroll(0, {behavior: auto}">Jump to top</scroll>

With offset:

<div x-data>
    <div x-ref="foo">
        ...
    </div>
    <button x-on:click="$scroll($refs.foo, {offset: 50})">Scroll to 50px before foo</scroll>
</div>
...
<div id="foo">
</div>
<div x-data>
    <button x-on:click="$scroll('#foo, {offset: 50}')">Scroll to 50px before #foo</scroll>
</div>
...
<button x-data x-on:click="$scroll(0, {offset: 50}">Jump to 50px before top (a bit daft but supported)</scroll>

With both:

<div x-data>
    <div x-ref="foo">
        ...
    </div>
    <button x-on:click="$scroll($refs.foo, {behavior: auto, offset: 50})">Jump to 50px before foo</scroll>
</div>
...
<div id="foo">
</div>
<div x-data>
    <button x-on:click="$scroll('#foo, {behavior: auto, offset: 50}')">Jump to 50px before #foo</scroll>
</div>
...
<button x-data x-on:click="$scroll(0, {behavior: auto, offset: 50}">Jump to 50px before top</scroll>

Demo (same as above)

---------------------------------------------------------------------

 $truncate

Example:

<div
    x-data="{ characters: 50, string: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.'}"
    x-text="$truncate(string, characters)"
    @click="characters = undefined">
    <!-- Text will show 'Lorem ipsum dolor sit amet, consectetur adipiscing...' and will reveal all when clicked-->
</div>

You may also pass a third argument to change the string that will be
appended to the end:

<div
    x-data="{ characters: 50, string: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.'}"
    x-text="$truncate(string, characters, ' (...)')">
    <!-- Text will show 'Lorem ipsum dolor sit amet, consectetur adipiscing (...)' -->
</div>

Demo

Optionally pass in options

By default, $truncate 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:

<div
    x-data="{ count: 5, string: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.'}"
    x-text="$truncate(string, { words: words, ellipsis: ' ...read more' })"
    @click="count = 0">
    <!-- Will start with 5 words, then increase to unlimited when clicked -->
</div>

Demo (same as above)

    Behind the scenes, for words, this uses sentence.split("
    ").splice(0, words).join(" ") which does not define a word in all
    languages.

---------------------------------------------------------------------

 $undo

Example:

<div x-data="{ number: 0 }" x-init="$track()">
    <button @click="number = Math.floor(Math.random() * 10)" x-text="number"></button>
    <button x-show="$history.length" @click="$undo()">undo</button>
</div>

Demo

The $undo 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:

<div x-data="{ number: 0; another: 0 }" x-init="$track('number')">
    <button @click="number = number + 1" x-text="number"></button>
    <button @click="another = another + 1" x-text="another"></button>
    <button x-show="$history.length" @click="$undo()">undo number only</button>
</div>

    Use $track(['prop1', 'prop2']) to track multiple properties

Demo

---------------------------------------------------------------------

 License

Copyright (c) 2020 Alpine Collective

Licensed under the MIT license, see LICENSE.md for details.

About

A collection of magic properties and helper functions for use with
Alpine.js

npmjs.com/alpine-magic-helpers

Topics

alpine alpinejs magic-helper alpine-collective

Resources

Readme

License

MIT License

Releases 17

 
v1.0.0 Latest
Feb 13, 2021
+ 16 releases

Sponsor this project

  * 
     
  * 
     
  * 
     
  * 
     

Learn more about GitHub Sponsors

Used by 13

 

  * @cinghie
  * @Braden-Preston
  * @cdubz
  * @InterNACHI
  * @iznyn
  * @mcseptian
  * @hhinkin
  * @pvduc-dev

+ 5

Contributors 10

  * @KevinBatdorf
  * @SimoTod
  * @HugoDF
  * @ryangjchandler
  * @atomgiant
  * @pomartel
  * @muzafferdede
  * @clmntgr
  * @markfirmware

Languages

  * JavaScript 100.0%

  * (c) 2021 GitHub, Inc.
  * Terms
  * Privacy
  * Security
  * Status
  * Docs

 

  * Contact GitHub
  * Pricing
  * API
  * Training
  * Blog
  * About

You can't perform that action at this time.
You signed in with another tab or window. Reload to refresh your
session. You signed out in another tab or window. Reload to refresh
your session.