PrimerLive (PrimerLive v0.2.1)

PrimerLive components can be used in Phoenix LiveView pages and regular (non-LiveView) views in Phoenix applications.

The Primer Design System provides a strong base for creating data driven applications such as rich CRUD applications with interactive forms.

Since this implementation closely adheres to the Primer CSS documentation, extending components with Primer's utility classes should be simple.

demo

Demo

PrimerLive Storybook

source-code

Source code

PrimerLive at GitHub

installation

Installation

install-primer_live

Install primer_live

Add PrimerLive as a dependency in your Phoenix application's mix.exs

{:primer_live, "~> 0.2.1"}

Run mix.deps get

add-css-and-javascript-dependencies

Add CSS and JavaScript dependencies

You can either use `npm`, or add the dependencies to the HTML file.

If you plan to use menus, dialogs, or drawers in your project, you will need to include JavaScript dependencies. If not, you may skip the JavaScript imports and hooks.

option-a-adding-dependencies-using-npm

Option A: Adding dependencies using npm

Add npm library primer-live to your assets/package.json. For a regular project, do:

{
  "dependencies": {
    "primer-live": "file:../deps/primer_live"
  }
}

If you're adding primer-live to an umbrella project, change the paths accordingly:

{
  "dependencies": {
    "primer-live": "file:../../../deps/primer_live"
  }
}

Now run the next command from your web app root:

npm install --prefix assets

If you had previously installed primer-live and want to get the latest JavaScript, then force an install with:

npm install --force primer-live --prefix assets

To ensure that the assets are installed before your application has started, and before it has been deployed, add "npm install" to the setup and deploy scripts in mix.exs.

For example:

defp aliases do
[
  setup: ["deps.get", "cmd npm --prefix assets install"],
  "assets.deploy": [
    "cmd npm --prefix assets install",
    "esbuild default --minify",
    "phx.digest"
  ]
]
end

Run mix setup to install the npm dependencies.

Add to assets/js/app.js:

import "primer-live/primer-live.min.css";
import { Prompt, Session } from "primer-live";

Also in assets/js/app.js, add Prompt and Session to the hooks:

let liveSocket = new LiveSocket("/live", Socket, {
  params: { _csrf_token: csrfToken },
  hooks: {
    Prompt,
    Session,
    // existing hooks ...
  },
});

option-b-adding-dependencies-to-the-html-file

Option B: Adding dependencies to the HTML file

Load the dependencies from a content delivery service such as unpkg.

CSS only

Add to root.html.heex:

<link rel="stylesheet" href="https://unpkg.com/primer-live/priv/static/primer-live.min.css" media="all">

CSS and JavaScript

Add to root.html.heex:

<link rel="stylesheet" href="https://unpkg.com/primer-live/priv/static/primer-live.min.css" media="all">
<script src="https://unpkg.com/primer-live/priv/static/primer-live.min.js"></script>

In assets/js/app.js, add global Prompt and Session to the hooks:

let liveSocket = new LiveSocket("/live", Socket, {
  params: { _csrf_token: csrfToken },
  hooks: {
    Prompt,
    Session,
    // existing hooks ...
  },
});

usage-in-liveview-pages

Usage in LiveView pages

To use components, use module PrimerLive:

defmodule MyAppWeb.MyLiveView do
  use MyAppWeb, :live_view
  use PrimerLive

  def render(assigns) do
    ~H"""
    <.button>Click me</.button>
    """
  end

end

usage-in-regular-views

Usage in regular views

In view files, for example in page_view.ex, use module PrimerLive:

defmodule MyAppWeb.PageView do
  use MyAppWeb, :view
  use PrimerLive
end

Then call the component on a page, for example in templates/page/index.html.heex:

<.button>Click me</.button>

list-of-components

List of components

PrimerLive.Component