# phoenix_page_meta usage rules
Rules apply to `phoenix_page_meta ~> 0.2`.
Per-page metadata for Phoenix LiveView apps: breadcrumbs, active-link state,
SEO meta tag rendering. Each LiveView declares one `%PhoenixPageMeta.PageMeta{}`
per action; the package handles the rest.
## The shape
As of 0.2.0 you use the prebuilt, config-driven `PhoenixPageMeta.PageMeta`
struct directly — there is **no per-app PageMeta module**.
1. **`config/config.exs`** — site-wide defaults and (optionally) extra fields.
2. **Each LiveView** — implements `PhoenixPageMeta.LiveView` callback
`page_meta/2`, calls `assign_page_meta/1` after data is loaded.
```elixir
# config/config.exs
config :phoenix_page_meta,
site_name: "MyApp",
twitter_site: "@myapp",
supported_locales: [:en, :es],
extra_fields: [icon: nil, modal: false]
```
```elixir
# in a LiveView
%PhoenixPageMeta.PageMeta{title: "Hello", path: "/hello"}
```
> The legacy `use PhoenixPageMeta` + hand-rolled `defstruct` approach is
> **deprecated** as of 0.2.0 (emits a compile-time warning). Prefer the
> prebuilt struct. The only thing the legacy path still offers is multiple
> distinct PageMeta modules (e.g. an umbrella with several endpoints).
## The struct
`PhoenixPageMeta.PageMeta`'s field set is assembled at compile time:
- **Base fields** (always present): `:title`, `:path`, `:breadcrumb_title`,
`:parent`, `:skip_breadcrumb`, `:description`, `:canonical_path`,
`:og_image`, `:og_image_alt`, `:json_ld`, `:locale`, plus `:noindex`
(default `false`).
- **Config-defaulted fields**: `:og_type`, `:site_name`, `:twitter_site`,
`:supported_locales` — their defaults come from `config :phoenix_page_meta`
(so they are set site-wide, overridable per page).
- **Extra fields**: from `config :phoenix_page_meta, extra_fields: [...]`. Bare
atoms and `{key, default}` pairs may be mixed; a later entry overrides an
earlier one.
`:title` and `:path` are required (`@enforce_keys`). Make extra fields required
with `config :phoenix_page_meta, extra_enforce_keys: [...]` (appended to
`:title`/`:path`).
> **Compile-time config.** `:extra_fields`, `:extra_enforce_keys`, `:og_type`,
> `:site_name`, `:twitter_site`, and `:supported_locales` are read with
> `Application.compile_env/3`. After changing them run
> `mix deps.compile phoenix_page_meta --force`.
## base_url and lang_path
These are resolved from config, not from the struct module:
- **`base_url`** — `config :phoenix_page_meta, :base_url` (a string,
`&Mod.url/0`, or `{m, f, a}`). If unset, the single running
`Phoenix.Endpoint` is auto-detected (memoized). Set `:endpoint`
(`config :phoenix_page_meta, endpoint: MyAppWeb.Endpoint`) or `:base_url`
explicitly if detection is ambiguous (e.g. multiple endpoints).
- **`lang_path`** — `config :phoenix_page_meta, :lang_path` (a `fun/2` or
`{m, f}`). Defaults to a locale-prefix swap (`/en/foo` → `/de/foo`).
In the common single-endpoint app, no base-URL config is needed at all.
## Module structure
```
PhoenixPageMeta # active?/2,3 (lib-level), config resolvers
PhoenixPageMeta.PageMeta # prebuilt config-driven struct (recommended)
PhoenixPageMeta.Breadcrumb # struct + build/1
PhoenixPageMeta.Components.Breadcrumbs # list/1 component
PhoenixPageMeta.Components.MetaTags # default/1 component
PhoenixPageMeta.Site # behaviour: base_url/0, lang_path/2
PhoenixPageMeta.LiveView # behaviour: page_meta/2 + assign_page_meta/1
```
## Standard fields
URL fields (`og_image`, `canonical_path`, `path`) accept either absolute URLs
(`https://...`) or relative paths (`/foo`). Relative paths are auto-prefixed
with `base_url` at render time. So `og_image: "/images/og.png"` produces
``.
`:site_name`, `:twitter_site`, and `:supported_locales` are typically set once
via config (site-wide) and rarely overridden per page.
`MetaTags.default` reads optional fields with `Map.get/2`, so a struct compiled
without a given extra field still renders.
## LiveView pattern
```elixir
# In MyAppWeb.live_view/0:
quote do
use Phoenix.LiveView, layout: ...
@behaviour PhoenixPageMeta.LiveView
import PhoenixPageMeta.LiveView, only: [assign_page_meta: 1]
end
# In each LiveView:
@impl PhoenixPageMeta.LiveView
def page_meta(socket, :show) do
%PhoenixPageMeta.PageMeta{
title: socket.assigns.location.name,
path: ~p"/locations/#{socket.assigns.location.slug}",
parent: %PhoenixPageMeta.PageMeta{title: "Locations", path: ~p"/locations"}
}
end
def handle_params(params, _uri, socket) do
{:noreply,
socket
|> assign(:location, load_location(params))
|> assign_page_meta()}
end
```
Alias `PhoenixPageMeta.PageMeta` in your web module's `html_helpers` so
templates can write `%PageMeta{}` unprefixed.
## active?/2,3
```elixir
PhoenixPageMeta.PageMeta.active?(page_meta, "/locations") # prefix match, query stripped
PhoenixPageMeta.PageMeta.active?(page_meta, "/locations", exact: true) # exact match only
PhoenixPageMeta.PageMeta.active?(page_meta, "/x?tab=open", query: true) # raw match (filter tabs)
```
The wrapper guards on `is_struct(page_meta, PhoenixPageMeta.PageMeta)` — wrong
type = `FunctionClauseError`.
Without `:exact`, a path is active if it equals the current path or is a prefix
followed by `/`. `/locations` is active on `/locations/123` but not on
`/location-foo`.
## breadcrumbs
`PhoenixPageMeta.PageMeta.breadcrumbs/1` (delegates to
`PhoenixPageMeta.Breadcrumb.build/1`) walks the `:parent` chain and returns
root-first `[%PhoenixPageMeta.Breadcrumb{title, path, first?, last?, page_meta}]`.
Pages with `:skip_breadcrumb: true` are filtered out — useful for modal or
overlay routes that should not appear as breadcrumb entries.
## Layout
```heex
<.live_title suffix=" | MyApp">{@page_title}
```
## Breadcrumbs component
Slot-based, owns `