stimulus-reactive
v1.0.0
Published
Reactivity for the Stimulus you already have.
Downloads
4
Readme
Stimulus Reactive
Reactivity for the Stimulus you already have
🚀 View the Shopping Cart Demo and the Controllers
When you love the refreshing simplicity of Stimulus but miss the reactivity of other big frameworks.
A Stimulus application's state lives in the DOM, but what if you could make that state reactive?
That is the core idea of Stimulus Reactive, a tiny library that brings the best of both worlds.
Stimulus Reactive automatically wires up valueChanged
, outletConnected
and outletDisconnected
handlers and keeps some internal reactive state in sync with those changes.
On a state change, anything that depends on that state gets automatically updated!
In the following example:
When a cart item gets added or removed, or an existing item's quantity or price is updated
- The cart total will show the correct value
- The checkout button will be enabled or disabled based on the total.
In effect
(pun intended) Stimulus Reactive allows you to declaratively specify the behavior of your controllers.
class CartItemController extends Controller {
static targets = ["total"];
static values = {
price: Number,
quantity: { type: Number, default: 1 },
};
static afterLoad(identifier, application) {
useStimulusReactive(identifier, application);
}
get total() {
return this.priceValue * this.quantityValue;
}
connect() {
// displayed total will be updated when price or quantity changes
this.effect(() => (this.totalTarget.textContent = this.total.toString()));
}
}
class CartController extends Controller {
static targets = ["checkout", "cartTotal"];
static outlets = ["cart-item"];
static afterLoad(identifier, application) {
useStimulusReactive(identifier, application);
}
get total() {
return this.cartItemOutlets.reduce((total, item) => total + item.total, 0);
}
connect() {
this.effect(() => {
// text content is kept in sync with cart total
this.cartTotalTarget.textContent = total.toString()
// checkout button is enabled only when balance is due
this.checkoutTarget.disabled = total == 0
});
// another effect for some other dependency
this.effect(() => ...);
}
}
Usage
State lives in a controller's values and connected outlets.
- Call
useStimulusReactive
in the staticafterLoad
method - In the
connect
lifecycle method specify controller behavior usingeffect
s - Effects will run whenever any dependency changes
This will be familiar to those coming from other frameworks like React, Vue etc.
That's pretty much it!
How does this work?
Under the hood Stimulus Reactive uses @vue/reactivity to do all the hard work.
Give it a go and hopefully this helps make your majestic monolith sparkle!