PhoenixLiveCalendar

A comprehensive calendar and scheduling component library for Phoenix LiveView.

Server-rendered calendar views with optional drag interactions, real-time PubSub sync, booking constraints, and Ecto persistence. Zero JavaScript required for the base layer.

Phoenix-first — it looks right without JavaScript

This is the guiding principle: every view (month, week, day, N-day, year, agenda, timeline, resource) is computed in Elixir and rendered as plain HEEx + Tailwind over the LiveView socket — no charting JS, no <canvas>, and nothing that has to boot on the client for the layout to be correct. The JS hooks are progressive enhancement only (drag-to-select / move / resize, the day-marker ticker, touch handling). With them absent the calendar still renders and works: navigation, view switching, date/event clicks, and the detail popover are all server-driven phx-clicks, and a day with multiple markers still shows its first marker (you only lose the cycling). Add the hooks for richer interaction; never depend on them for the page to look right.

Features

• 8 view types: Month, Week, Day, N-day (flexible), Year, Agenda, Timeline, Resource columns
• Pure Elixir base layer: Works without any JavaScript
• Heatmaps: Heatmap.markers/2 maps per-day numbers onto intensity-tinted month/year cells (GitHub-contributions style) — :fill or quieter :dot style, palette presets (:success/:heat/:cool/:mono)
• Widgets: Widgets.next_events/week_strip/activity_grid/mini_timeline + MiniCalendar — the most compressed useful form of each surface for ~200×150px dashboard cells
• Layers: named event sets with a legend of toggle chips, filtered server-side — withheld layers never reach the client
• Semantic color tokens: Event.color takes :primary-style atoms or app-configured tokens as well as raw classes
• Customization slots forwarded through the CalendarComponent (:event, :day_cell, :time_label, …)
• Range-driven windowing: events_mode: :window renders only the visible slice — pair with on_date_range_change
• Progressive enhancement: Optional JS hooks for drag-to-select, drag-to-move, resize
• Real-time sync: Optional PubSub integration for multi-user calendars
• Booking system: Availability windows, slot constraints, capacity, buffers, validation
• Accessibility-minded: ARIA grid roles, roving tabindex, and screen-reader labels (full arrow-key grid navigation + focus restoration are on the roadmap)
• RTL support: Full right-to-left layout for Arabic, Hebrew, Persian, Urdu
• i18n: All labels translatable via Gettext or override map
• Tailwind CSS: Uses daisyUI semantic classes, works with any Tailwind theme
• Optional Ecto: Opt-in persistence with Oban-style versioned migrations
• Dashboard-ready: All components work at any container size

View maturity: All eight views render server-side and work today. Month, week and day are the polished, phone-tuned views (the time grids gained day markers, dense all-day lanes, detail event blocks and responsive columns in 0.3). Timeline and resource were substantially hardened in 0.3 (midnight clamping, fitted windows, sticky columns, now line, bar labels, shared day-segment math); year and agenda are functional but less refined.

Installation

Add phoenix_live_calendar to your dependencies:

def deps do
  [
    {:phoenix_live_calendar, "~> 0.3.0"}
  ]
end

Add to your assets/css/app.css so Tailwind scans the component templates:

@source "../../deps/phoenix_live_calendar";

Optional: JS hooks

For drag interactions, add to assets/js/app.js:

import "../../deps/phoenix_live_calendar/priv/static/assets/phoenix_live_calendar.js"

let liveSocket = new LiveSocket("/live", Socket, {
  hooks: { ...window.PhoenixLiveCalendarHooks, ...Hooks }
})

Optional: Ecto persistence

# config/config.exs
config :phoenix_live_calendar, repo: MyApp.Repo

# Generate and run the migration
mix ecto.gen.migration add_phoenix_live_calendar

Edit the migration:

defmodule MyApp.Repo.Migrations.AddPhoenixLiveCalendar do
  use Ecto.Migration

  def up, do: PhoenixLiveCalendar.Store.Ecto.Migrations.up(version: 1)
  def down, do: PhoenixLiveCalendar.Store.Ecto.Migrations.down(version: 1)
end

Quick Start

defmodule MyAppWeb.CalendarLive do
  use MyAppWeb, :live_view

  def mount(_params, _session, socket) do
    events = [
      PhoenixLiveCalendar.event("1", ~U[2026-04-01 09:00:00Z],
        title: "Team Standup",
        end: ~U[2026-04-01 09:30:00Z],
        color: "bg-primary"
      ),
      PhoenixLiveCalendar.event("2", ~D[2026-04-05],
        title: "Company Holiday",
        all_day: true,
        color: "bg-success"
      )
    ]

    {:ok, assign(socket, events: events)}
  end

  def render(assigns) do
    ~H"""
    <.live_component
      module={PhoenixLiveCalendar.CalendarComponent}
      id="my-calendar"
      events={@events}
      views={[:month, :week, :day, :agenda]}
      on_date_select={fn date -> send(self(), {:date_selected, date}) end}
      on_event_click={fn id -> send(self(), {:event_clicked, id}) end}
    />
    """
  end

  def handle_info({:date_selected, date}, socket) do
    IO.inspect(date, label: "Selected date")
    {:noreply, socket}
  end

  def handle_info({:event_clicked, event_id}, socket) do
    IO.inspect(event_id, label: "Clicked event")
    {:noreply, socket}
  end
end

Configuration Options

Callbacks

Heatmaps

# Date => number, bucketed onto an intensity palette
markers = PhoenixLiveCalendar.Heatmap.markers(minutes_by_day, scale: :quantile)

<.live_component module={PhoenixLiveCalendar.CalendarComponent} id="history" day_markers={markers} />

# quieter dot style, preset palettes (:success | :heat | :cool | :mono)
PhoenixLiveCalendar.Heatmap.markers(data, style: :dot, palette: :heat)

Widgets

The most compressed useful form of each surface, for dashboard cells:

<PhoenixLiveCalendar.Widgets.next_events events={@events} limit={3} />
<PhoenixLiveCalendar.Widgets.week_strip events={@events} />
<PhoenixLiveCalendar.Widgets.activity_grid data={@minutes_by_day} />
<PhoenixLiveCalendar.Widgets.activity_month data={@minutes_by_day} />
<PhoenixLiveCalendar.Widgets.mini_timeline date={@today} resources={@resources} events={@events} />
<PhoenixLiveCalendar.Components.MiniCalendar.mini_calendar date={@today} events_by_date={@by_date} />

Using Individual Views

You can use any view component standalone without the LiveComponent wrapper:

<PhoenixLiveCalendar.Views.MonthGrid.month_grid
  date={~D[2026-04-01]}
  events={@events}
  on_date_click={JS.push("date_clicked")}
/>

<PhoenixLiveCalendar.Views.Agenda.agenda
  date={Date.utc_today()}
  events={@events}
  days={14}
/>

License

MIT License - see LICENSE for details.