live_view_responsive

Media queries for responsive design in Phoenix LiveView, a server-rendered Elixir framework. Heavily inspired by react-responsive.

Information
Installation
Example Usage
- Using `<.media_query>` Component
- Using Media Query Assigns
API
Easy Mode
FAQ
Contributing

Information

live_view_responsive provides an easy way to manage media queries in Phoenix LiveView applications. It allows you to create responsive designs without the need to write custom media queries or learn Tailwind CSS.

Installation

Before you begin, ensure you have the following prerequisites:

Elixir 1.13+
Phoenix LiveView 0.20+

Add live_view_responsive to your list of dependencies in mix.exs:

# mix.exs
def deps do
  [
    {:live_view_responsive, "~> 0.1.1"}
  ]
end

In assets/js/app.js add live_view_responsive hooks:

// assets/js/app.js
import {
  LiveViewResponsiveHook,
  LiveViewResponsiveMediaQueryHook,
} from "live_view_responsive";

let liveSocket = new LiveSocket("/live", Socket, {
  hooks: {
    LiveViewResponsiveHook,
    LiveViewResponsiveMediaQueryHook,
  },
});

Example Usage

Using `<.media_query>` component

defmodule ExampleAppWeb.Example do
  use Phoenix.Component

  import LiveViewResponsive

  def example(assigns) do
    ~H"""
    <.media_query max_width={1224}>
      <p>You are on a tablet or mobile</p>
    </.media_query>
    <.media_query min_width={1225}>
      <p>You are on a desktop or laptop</p>
      <.media_query min_width={1500}>
        <p>You also have a huge screen</p>
      </.media_query>
    </.media_query>
    """
  end
end

✅ Toggles CSS display property on media query change with zero latency. ⚡
✅ No need to write custom media queries or learn Tailwind.

Using media query assigns

defmodule ExampleAppWeb.ExampleComponent do
  use ExampleAppWeb, :live_component

  use LiveViewResponsive

  @impl true
  def mount(socket) do
    socket =
      socket
      |> assign_media_query(:tablet_or_mobile, max_width: 1224)
      |> assign_media_query(:desktop_or_laptop, min_width: 1225)
      |> assign_media_query(:portrait, orientation: "portrait")

    {:ok, socket}
  end

  def render(assigns) do
    ~H"""
    <div>
      <.live_view_responsive myself={@myself} />

      <h1>Device test</h1>
      <p :if={@tablet_or_mobile}>
        You are on a tablet or mobile phone
      </p>
      <p :if={@desktop_or_laptop}>
        You are on a desktop or laptop
      </p>
      <p>
        You are in
        <%= if assigns.portrait, do: "portrait", else: "landscape" %>
        orientation
      </p>
    </div>
    """
  end
end

✅ Gives greater control over what is rendered.
✅ Assigned media queries are just boolean values updated automatically.

Note: Works only in live components. Both use LiveViewResponsive and <.live_view_responsive myself={@myself} /> are required to make media query assigns work.

API

Using properties

To make things more idiomatic to Phoenix LiveView, its preferred to use snake_case shorthands to construct media queries, but the kebab-case syntax is also supported.

For a list of all possible shorthands see media_types_and_features.ex.

If shorthand accepts a string or number, any number given will be expanded to px (1234 becomes 1234px).

Media query assigns can be constructed like this:

socket
|> assign_media_query(:tablet, min_width: 600, max_width: 900)

or with media query component attributes:

<.media_query min_width={600} max_width={900}>
  You are on a tablet
</.media_query>

Supported media features

orientation, scan, aspect_ratio, device_aspect_ratio, height, device_height, width, device_width, color, color_index, monochrome, resolution.

Most support modifiers min_ and max_.

Supported media types

all, grid, aural, braille, handheld, print, projection, screen, tty, tv, embossed.

To use media types pass them with true or false value.

socket
|> assign_media_query(:screen, screen: true)      # screen
|> assign_media_query(:not_screen, screen: false) # not screen

Custom media query

Sometimes you need to create a complex query or use a bleeding edge feature. In such cases, you can pass a custom query string.

socket
|> assign_media_query(:tablet, query: "(min-width: 600px) and (max-width: 900px)")

Initial value or hiding elements until media query is synced

Because assign_media_query calls need to receive information from the front-end, their values are all set to false on the first render.

💡 The <.media_query> component is always up to date, so it's safe to use without additional checks.

Hiding elements until synced

To hide elements until information about matching media queries is received from the front-end for the first time and prevent flickering, check the @live_view_responsive_synced assign.

def render(assigns) do
  ~H"""
  <div>
    <.live_view_responsive myself={@myself} />

    <span :if={@live_view_responsive_synced}>
      <%= if @small_screen, do: "Small screen", else: "Big screen" %>
    </span>
  </div>
  """
end

Initial value

Alternatively, to make the media query match on the first render, add the initial: true keyword:

|> assign_media_query(:mobile, min_width: 600, initial: true)
|> assign_media_query(:desktop, min_width: 1200)

Easy mode

You can create your application-specific breakpoints and reuse them easily.

defmodule ExampleApp.LiveViewResponsive do
  @moduledoc """
  Generates breakpoints for live_view_responsive design.

  For each breakpoint new component named `{breakpoint}_media_query` is generated, for example:

  <.mobile_media_query>
    You are on a mobile
  </.mobile_media_query>

  And a function named `assign_{breakpoint}_media_query` is created, for example:

  socket
  |> assign_mobile_media_query(initial: true)
  |> assign_tablet_media_query()
  """

  use LiveViewResponsive.Breakpoints, [
    mobile: [max_width: 700],
    tablet: [min_width: 701, max_width: 1200],
    desktop: [min_width: 1201],
  ]
end

Then you can use the defined module instead of LiveViewResponsive in your components.

defmodule ExampleAppWeb.Example do
  use Phoenix.Component

  import ExampleApp.LiveViewResponsive

  def example(assigns) do
    ~H"""
    <div>
      <.mobile_media_query>
        You are on a mobile
      </.mobile_media_query>
      <.tablet_media_query>
        You are on a tablet
      </.tablet_media_query>
      <.desktop_media_query>
        You are on a desktop
      </.desktop_media_query>
    </div>
    """
  end
end

Same thing with live components:

defmodule ExampleAppWeb.ExampleLiveComponent do
  use ExampleAppWeb, :live_component

  use ExampleApp.LiveViewResponsive

  @impl true
  def mount(socket) do
    socket
    |> assign_mobile_media_query()
  end

  def render(assigns) do
    ~H"""
    <div>
      <.live_view_responsive myself={@myself} />

      <span :if={@mobile}>
        You are on a mobile
      </span>
      ...
    </div>
    """
  end
end

FAQ

Changes of the new variable based on media query assigns do not cause rerender of live component

It happens when you calculate new variables based on the media query assigns in the `render/1` callback. You have to assign them in the `update/2` callback instead. Given such media query assigns: ```elixir @impl true def mount(socket) do socket |> assign_media_query(:mobile, min_width: 600) |> assign_media_query(:desktop, min_width: 1200) end ``` ❌ Do not create new variables based on these assigns in the `render/1` callback. LiveView will not render changes when `small_screen` is updated, even if you put it into assigns. ```elixir def render(assigns) do # this will not work small_screen = assigns.mobile and not assigns.desktop ~H"""

Small screen

""" end ``` ✅ Instead, calculate new variables in `update/2` callback: ```elixir @impl true def update(assigns, socket) do small_screen = assigns.mobile and not assigns.desktop socket = assign(socket, :small_screen, small_screen) {:ok, assign(socket, assigns)} end def render(assigns) do ~H"""