DEV Community: Matt Whitworth

Tooltips in Phoenix LiveView

Matt Whitworth — Thu, 13 Feb 2025 19:45:06 +0000

There are a few options to integrate tooltip functionality into Phoenix LiveView. This article covers integrating a Phoenix LiveView with one popular library tippy.js, ensuring any updates from LiveView are reflected in tooltip state.

Background

tippy.js is a powerful, versatile and lightweight Javascript tooltip library. It provides the logic (and optional styling) of elements that “pop out” and float next to a target element. Although the last version was released three years ago, it receives over a million downloads a week. The approach here can be transferred to other libraries like Floating UI.

With Phoenix LiveView applications, we may wish to have the content of tooltips (and their styling) vary depending on the current application state.

Because tippy.js takes care of configuring and rendering the tooltip, and stores internal state outside of the element, we’ll need to use a LiveView client hook to ensure updates to the element are reflected in the tippy.js internal state associated with the element.

(Need a refresher on how to integrate client-side libraries that take care of rendering? See this previous article: Phoenix LiveView, hooks, and push-event: json-view)

Installation

In a Phoenix LiveView application, let's install the library:

npm install --prefix assets tippy.js

We’ll need to now include the Javascript and (default) CSS in separate ways.

For the Javascript code - We can then include tippy.js in assets/js/app.js, with the hook to come:

import tippy from "tippy.js"

And the CSS can be imported in assets/css/app.css:

@import "tippy.js/dist/tippy.css";

Configuring tooltips (tippy.js)

With this library now included in our application, we can now invoke tippy, a function that creates tooltip context associated with a particular element. We can use the returned value (an instance) to control, update and invoke the tooltip as necessary.

tippy.js includes a number of configurable properties (with associated defaults) - the documentation covers all of these.

We can keep the need for custom Javascript code very light, and integrate with LiveView well, by using data-tippy attributes. We can access these properties via the dataset attribute, which we’ll do so in the hook in the following section.

When creating the tooltip instance, the tippy function actually reads these data-tippy elements. However, if we update those attribute values with LiveView, it won’t update the tooltip. This is a limitation of the library, documented in the FAQ.

So, keeping LiveView’s update mechanism in mind, we’ll have to write a hook to create the tooltip instance when the element is mounted, and update the properties correctly when the element is updated.

Let’s take a look at the element first, to see what kind of state we’ll need to deal with.

The HTML element

Here’s a button element that will integrate with the hook we’re about to write:

<button id="example-button" phx-hook="Tippy" data-tippy-content="Hello!" data-tippy-placement="bottom">
    Hover over me
</button>

There are several things to note here:

id is required for all elements that have a phx-hook associated with them, so Phoenix LiveView can associate internal state by element ID
phx-hook associates a particular hook. Only (at most) one hook is permitted per element
data-tippy- is the prefix for each attribute. We’ll need to process these dataset elements (see the dataset property documentation) to pass a configuration object when we come to update the properties associated with the tooltip. In short: data-tippy-placement=”bottom” in the DOM becomes this.el.dataset.tippyPlacement // => “bottom” in Javascript.

The LiveView hook

Here’s the code for the hook. Let’s go through the below section by section.

const Hooks = {
  Tippy: {
    mounted() {
      this.instance = tippy(this.el);
    },
    updated() {
      this.instance.setProps(
        Object.fromEntries(
          Object.entries(this.el.dataset)
            .filter(([k]) => k.startsWith("tippy"))
            .map(([k, v]) => [
              this.tippyPropName(k),
              v
            ])
        )
      );
    },
    destroyed() {
      this.instance.destroy();
    },

    tippyPropName(k) {
      const strippedName = k.replace("tippy", "");
      return strippedName.charAt(0).toLowerCase() + strippedName.slice(1);
    },
  },
};

mounted()

When the element is first added to the page, the mounted() callback is invoked. We’ll need to create the tooltip instance associated with the DOM element (this.el):

this.instance = tippy(this.el);

After this, tippy.js takes care of attaching to the relevant DOM events and invoking the logic to display the tooltip.

updated()

As noted above, tippy.js doesn’t update its internal state if the values of attributes change.

this.instance.setProps(
Object.fromEntries(
Object.entries(this.el.dataset)
.filter(([k]) => k.startsWith("tippy"))
.map(([k, v]) => [
this.tippyPropName(k),
v
])
)
);

Step by step:

It starts with this.el.dataset, which contains all data attributes of an HTML element.
It filters these attributes to only include those that start with "tippy" (data-tippy in the HTML)
For each filtered attribute, it transforms the attribute name into a valid Tippy.js property name using a tippyPropName method.
It creates an object from these transformed key-value pairs.
Finally, it sets these properties on the Tippy.js instance using setProps().

(Take care that the representation within the tooltip’s data attributes is something that is either a string or a JSON representation, depending on the type of the tippy.js attribute.)

Another alternative: we could invoke tippy again to create another tooltip. But this has the clearest purpose and intention, even if the logic to transform attribute names isn’t necessarily easy to parse.

destroyed()

Without this, tippy.js tooltip instances accumulate during LiveView updates, causing memory leaks.

tippyPropName(k)

We need to remove the tippy prefix from the property name, and convert the casing of the remaining string (from a leading uppercase character to a lower one). So tippyShowOnCreate becomes showOnCreate, the object key that the setProps method expects.

Alternatives

tippy.js is by no means the only tooltip library that can be integrated with Phoenix LiveView:

alpine-tooltip is a popular plugin for Alpine.js, commonly used as a simple Javascript dynamic layer in Phoenix LiveView applications
Floating UI is a library (superseding popper.js) that helps you create “floating” elements such as tooltips, popovers, dropdowns and more. Floating UI is framework-independent.
Use Phoenix LiveView component libraries like salad_ui or Chelekom, which contain their own tooltip component implementations.

Conclusion

Integrating tippy.js with Phoenix LiveView provides a powerful and flexible solution for implementing tooltips in your application. By utilizing a LiveView client hook, we can ensure that any updates to the tooltip content or styling are seamlessly reflected in the tippy.js internal state.

This approach allows for dynamic, state-dependent tooltips that respond to changes in the application's context, enhancing the user experience and interactivity of your Phoenix LiveView application.

While tippy.js is a popular choice, it's worth noting that there are alternative libraries and approaches available for implementing tooltips in Phoenix LiveView. Whether you choose tippy.js, Alpine.js plugins, Floating UI, or Phoenix-specific component libraries, the key is to find a solution that best fits your project's needs and integrates smoothly with LiveView's update mechanism.

Phoenix LiveView, hooks and push_event: json_view

Matt Whitworth — Tue, 10 Dec 2024 16:50:50 +0000

Phoenix LiveView is a powerful framework built on Elixir, and offers an innovative approach to building real-time web interfaces without the need for extensive Javascript.

However, integrating with existing client-side libraries, like those for graphing, visualisation or rendering, can sometimes prove a challenge.

In this article, we’ll explore how we can integrate Phoenix LiveView with Javascript libraries that render to the DOM directly.

We’ll come across hooks, which allow us to run Javascript on certain lifecycle elements for a given element, and how these hooks enable streams of events (using push_event in LiveView and pushEvent in Javascript) to allow bi-directional real-time communication between client and server.

Background

TLDR: In Phoenix LiveView, you can use hooks and push_event to push data, and have the client-side library handle the rendering.

json-view (demo) - which displays JSON objects on a webpage as a tree that can be expanded and collapsed - is a good example of how some client-side Javascript libraries take control of rendering to the DOM and interaction with it.

Let’s work through an example of how to integrate this with JSON data provided by the (LiveView) server. We’ll send some static data from the backend in response to an event, but this data could come from any source.

The following will assume you’ve set up a Phoenix project using mix phx.new, with LiveView enabled.

Library setup

There are multiple ways to incorporate a Javascript package as part of the page’s Javascript.

Recommending a preferred setup is outside the scope of this article, but there are two main ways:

assets/vendor - in the typical LiveView project template, topbar is placed in this directory and included in the assets/app/app.js entrypoint file. This is suitable for smaller, more stable libraries in general, particularly if a single file version of the library is provided.
NPM/Yarn - esbuild and webpack can pack referenced node_modules file into a single distribution file. This is suitable for larger, more complex libraries that change more frequently.

The problem with json-view

There are two incompatible models of rendering when we try to combine the two libraries.

LiveView follows the declarative model - you design the view, determine what data should be displayed, and LiveView works out which elements of the page need to change when the underlying data is changed.

It achieves this by using socket assigns in render:

def render(assigns) do
  ~H"""
  <p>Hello <%= @name %></p>
  """
 end

However, libraries like json-view work on the imperative model. We specify the steps required to display the data in Javascript, outside the layout of the DOM itself:

import jsonview from '@pgrabovets/json-view';

const data = '{"name": "json-view", "version": "1.0.0"}'
const tree = jsonview.create(data);
jsonview.render(tree, document.querySelector('.tree'));

These two models are at odds. We have seemingly no way to match up the two methods of rendering data (declarative and imperative), but we need libraries like json-view to render rich interfaces on the client.

Fundamentally - we need to run Javascript code when the server prompts a change of page state. Let’s take a look at hooks, which helps to reconcile these two rendering models.

Hook setup

In LiveView, hooks are the way to provide bidirectional communication between the (browser) client and (LiveView) server, with the core object of communication being the event.

Hooks are defined in the LiveSocket and attached to an element using the phx-hook attribute. There are a number of callbacks - but we’ll focus on the mounted callback, since we can co-ordinate everything else via events. You can supply callbacks for other life-cycle events too - check the docs.

Within a callback like mounted, the hook sends events to the backend using this.pushEvent, and handles events from the server by registering a handler for a particular event name using this.handleEvent.

It’s important to note only one hook is permitted per element, so you only need to reason about one stream of events between client and server.

With that knowledge in mind - let’s define a JsonView hook that registers an event handler, that eventually calls jsonview.render on the element to render the tree of data.

import { Socket } from 'phoenix';
import jsonview from '@pgrabovets/json-view';

const JsonViewHook = {
  mounted() {
    this.handleEvent("render_json", ({ data }) => {
      this.el.innerHTML = "";
      const tree = jsonview.create(data);
      jsonview.render(tree, this.el);
    });
  }
}

const liveSocket = new LiveSocket(
  "/live",
  Socket,
  {hooks: { JsonView: JsonViewHook }, ...}
 );
...

We do several things in these several lines of code:

We define a JsonViewHook object with a mounted function. This function will be called when the element with this hook is mounted in the DOM.
Inside mounted, we set up an event listener for a custom event called "render_json". This event will be triggered from our LiveView.
When the event is received, it expects a data parameter containing the JSON to be rendered.
We clear the existing content of the element.
We use jsonview.create and jsonview.render to render the JSON data into our element.

To use this hook - we’ll just need to add the phx-hook attribute with the name of the hook (”JsonView”) to an element:

<div id="json-container" phx-hook="JsonView"></div>

Sending events to the server

We’ll just need to trigger an event from the backend to provide this data. We’ll leave this outside the scope of this article for now - perhaps a button could trigger an event to the backend? - but you could use this.pushEvent from the mounted hook like so:

mounted() {
  this.pushEvent("send_json", {});
}

to send an event to the LiveView server that can be handled with handle_info. The relevant section of the LiveView documentation covers more possibilities with this.pushEvent, including a scenario where a handler function can be specified to handle a reply payload directly.

Sending events from the server

push_event/3 is the way to push an event from LiveView to the browser. It can be called at any point - including in mount - though a good practice is to ensure that the page and all its elements are in a known state before sending these events. Otherwise - you’ll have events silently being dropped during page setup - a sure route to unpredictability!

Let’s write a handle_event clause for an event we might receive from the client, which pushes an event to the client:

def handle_event("send_json", _params, socket) do
  {:noreply, push_event(socket, "render_json", %{data: [1, 2, 3]})}
end

That’s it! And there’s flexibility here too. Registering event handlers with names on both the client and the server marks a clear separation between the handling of the event and how the event is raised.

Further integration

We’ve seen a simple example of the integration between client and server. A common extension of this would be to scope certain updates to certain elements, through the use of event parameters and element attributes. This helps to reduce the amount of unnecessary events and handler work.

This event handling can also be expanded for tighter client-side library integration with the backend. For example, typically these Javascript libraries emit higher-level user interaction events. Our library example, json-view, doesn’t do this, but a charting library like chart.js does.

However, from a user interaction standpoint, a round-trip to the server for processing should be generally avoided. Typically, any rendering update based on events would be handled by the rendering library client-side.

But capturing user activity for other reasons is a common use case. This includes monitoring, logging and analysis. These don’t require a response, so pushEvent from within a hook can be ideal for this type of asynchronous processing on the server.

Conclusion

Integrating powerful Javascript client-side libraries that require control over the DOM is a key part of creating rich, dynamic user interfaces. Not all page updates need to be real-time, and so retaining LiveView offers a powerful yet simple way to continue to control other page state.

Becoming familiar with LiveView hooks and their associated events makes integrating these with data that originates from the server possible. It’s also important to note that not all user interactivity require a round-trip to the server, and the interfaces you build will be more flexible and responsive when you use powerful Javascript libraries.

For loops and comprehensions in Elixir - transforming imperative code

Matt Whitworth — Tue, 03 Dec 2024 17:18:25 +0000

In this article, we’ll cover some common uses of for loops and comprehensions in Python, how to analyze an existing loop, and how to transform them into their equivalent expressions in Elixir, using the functions in the Enum module and comprehensions.

We’ll focus on:

transforming a collection of data through a function (map)
filtering values into or out of a collection (filter)
producing a single aggregate value or structure, such as an average (reduce or fold)

We’ll finish off with a basic example that combines all three!

Python

For loops

In Python, for loops typically feature interleaved processing - the steps are combined together into the same clause or body. Here’s an example that squares the first two even numbers:

result = 0
for num in [1, 2, 3, 4, 5]:
    if num % 2 == 0:
        result += num ** 2
print(result)  # Output: 20

One challenge of this interleaved body is to:

identify each step, and…
work out what type of step it is.

Breaking apart each step allows you to understand the transformations taking place, eliminate any unnecessary ones, and rewrite those steps into another language construct or higher-level function.

Annotating the function above results in:

result = 0
for num in [1, 2, 3, 4, 5]:
    ## Filter
    if num % 2 == 0:
        ## Reduce (result += ) and Map (num ** 2)
        result += num ** 2
print(result)  # Output: 20

The steps

As a result - the order of steps are:

Filter “out” odd numbers/”in” even numbers
Map numbers (e.g. 2) to their corresponding square number (e.g. 4)
Reduce to a sum of the squared even numbers

Comprehensions

Comprehensions in Python are simple ways to map and filter collections like lists and dictionaries. They don’t offer a way to reduce the result, but we can use built-in functions like sum to transform the above to process the result of the comprehension:

result = sum(num ** 2 for num in [1, 2, 3, 4, 5] if num % 2 == 0)
print(result)  # Output: 20

With comprehensions, the expression divides the map step (num ** 2) and filter step (if num % 2 == 0) clearly. sum is the reduce step here.

It’s easy to skim through these comprehension expressions in Python, and it places a useful upper limit on the complexity of a comprehension.

With this background, and a better understanding of the structure and limitations of Python’s processing constructs, let’s proceed to rewriting the above Python code using Elixir’s comprehensions and Enum pipelines!

Mapping: Enum.map and generators

How can we write the step to square numbers? In Elixir, it’s simple!

Using Enum.map:

Enum.map([1, 2, 3, 4, 5], & &1 ** 2)

and using comprehensions (for):

for n <- [1, 2, 3, 4, 5], do: n ** 2

The <- represents a generator expression, generating values to be used in the body of the for expression, after do:

Filtering: Enum.filter and filters

Easy to do with Enum.filter (or Enum.reject):

[1, 2, 3, 4, 5]
|> Enum.filter(& rem(&1, 2) == 0)
|> Enum.map(& &1 ** 2)

We’ll want to filter out odd numbers before they are squared, so we place it in the right place in the pipeline - before Enum.map.

Using comprehensions, we can add a second expression to the head of the comprehension, a filter, which is a boolean test:

for n <- [1, 2, 3, 4, 5], rem(n, 2) == 0, do: n ** 2

The rem(n, 2) == 0 expression then discards any elements that return false (or nil), leaving [2, 4] as the numbers that are actually passed to the body (do: n ** 2) of the comprehension.

Reduce -> Enum.reduce and reduce:

Using Enum.reduce/2, we can convert a list of squared numbers into their sum by adding to an accumulator. The first element is used as the initial value of the accumulator if we don’t specify an initial value for the accumulator (Enum.reduce/3), and that’s handy here:

[1, 2, 3, 4, 5]
|> Enum.filter(& rem(&1, 2) == 0)
|> Enum.map(& &1 ** 2)
|> Enum.reduce(& &1 + &2)

With comprehensions, we have even more power than the Python equivalent. We can add a reduce step by adding another clause to the head:

for n <- [1, 2, 3, 4, 5], rem(n, 2) == 0, reduce: 0, do: acc -> acc + n ** 2

making two changes here:

adding a reduce: 0 clause to the head, to specify that we will accumulate a value whose initial value is 0
changing the for body to capture an acc value (the accumulator) that we can add the current squared value to.

Built-in functions: Enum.sum

As a general rule, we should express the data we want to transform in the highest-level way possible. It’s useful to think of Enum.reduce as the lowest level functional transformation, since all other data processing can be rewritten in terms of it.

The Enum module contains plenty of higher-level functions, typically involving reducing a list of values to a single aggregate value, like a sum, maximum or minimum. In this case, we’d like the sum of the elements.

For Enum pipelines, this is straightforward:

[1, 2, 3, 4, 5]
|> Enum.filter(& rem(&1, 2) == 0)
|> Enum.map(& &1 ** 2)
|> Enum.sum()

There is not a way to represent these high-level aggregate functions in comprehensions, so we can pipe the output of the comprehension into a Enum.sum call like so, similar to how we did in Python:

(for n <- [1, 2, 3, 4, 5], rem(n, 2) == 0, do: n ** 2) |> Enum.sum()

Mixing different forms should generally be avoided, especially if the transformation is a simple one, as it results in less mental load for the reader - the reduce: form above is actually clearer to read despite being lower-level.

Which Elixir expression is better?

To summarise, we’ve ended up with two forms which could be considered idiomatic. For Enum pipelines:

[1, 2, 3, 4, 5]
|> Enum.filter(& rem(&1, 2) == 0)
|> Enum.map(& &1 ** 2)
|> Enum.sum()

and comprehensions:

for n <- [1, 2, 3, 4, 5], rem(n, 2) == 0, reduce: 0, do: acc -> acc + n ** 2

Easy to read code should be straightforward to scan through, without ambiguity or stumbling over expressions. I think both forms fill that criteria, as:

they follow a single consistent form - either Enum pipelines or comprehensions
each expression corresponds to a single processing step
it can be read top-to-bottom or left-to-right without interruption

Conclusion

Writing these transformations can be done in several different ways in Elixir, and it is easy for a codebase to vary styles, especially as code is changed and processing becomes more complicated over time.

PureType can break down and analyze Enum pipelines and comprehensions to represent them in their clearest and most idiomatic form, learning your preferences and increasing your code’s readability and clarity for others on the team. Try it out today!