Building sites
Widgets
A widget is one piece of content. Its kind picks the renderer and its settings belong to that renderer; spacing, alignment, colour and visibility of its box are the layout described in The page builder. Every widget's box carries the classes gsy-widget gsy-widget-<kind>.
Most widgets left unconfigured (an image with no picture, an empty list) show a dashed hint in the builder and nothing on the published page.
Basics
| Kind (label) | Shows | Main settings |
|---|---|---|
heading (Heading) | a heading | text (wrap words in == to highlight them in the accent colour), level 1 to 6 (default 2), size xs, s, m, l, xl, xxl (default follows the level), font body for the body typeface, weight 300 to 800, color |
text (Text) | rich text | html from the editor (paragraphs, headings 2 to 4, bold, italic, links, lists, quotes, code, images), size s, l, xl |
image (Image) | a library image | media_id, size (thumb, small, medium default, large, hero), aspect (auto or W:H such as 16:9, cropped around the focal point), alt, caption, width (a CSS length, for logos and icons), src (an outside address instead of a library item) |
file (File) | a download link with the file's name, type and size | media_id, label (defaults to the file name) |
button (Button) | a link styled as a button | label, href, style (solid default, outline, link), arrow (a trailing arrow), background, color, new_tab |
list (List) | short items | items (one per line), style (bullets default, numbers, checks, none, inline) |
features (Feature list) | items with an icon, title and line of text | items of { media_id, title, text, href }, columns 1 to 4 (default 3; one column on phones), icon_size (CSS length, default 60px), title_size s, m, l |
link-panels (Link panels) | stacked links, each with an arrow block | items of { title, text, href }, border and accent colours |
quote (Quote) | a pull quote | text, cite |
icon (Icon) | a built-in icon, optionally labelled | name, size (CSS length, default 2rem), color, label, stack (label underneath) |
stat (Statistic) | a big number with a caption | value, prefix, suffix, label, color |
divider (Divider) | a horizontal rule | style (solid, dashed, dotted), color, width (percent, default 100), thickness (CSS length) |
spacer (Spacer) | empty space | height (CSS length, default 2rem) |
gallery (Gallery) | a grid of library images | media_ids, columns 2 to 6 (default 3; two on phones), ratio (4/3 default, 1/1, 16/9, 3/4, 3/2), size (default medium), captions |
video (Video) | a video file with the browser's own player | media_id or src (the address of a video file), poster_media_id, controls (default on), autoplay (muted and looping, for backgrounds), caption |
code (Custom code) | hand-written HTML, CSS and JavaScript | html, css, js (runs with el bound to the widget's content); served unfiltered, so saving it needs the manage site permission |
The icon names are arrow-right, check, star, heart, phone, mail, pin, clock, calendar, user, users, home, search, shield, leaf, tool, hammer, truck, globe, camera, chat, info, tag, sun, gift, lightning, ruler and quote. They are drawn in the current colour, so they suit any theme.
The image widget writes a <picture> element offering AVIF, then WebP, then the original format, each with every generated size, so browsers pick the smallest file that fills the space. Alt text and caption fall back to the ones set on the item in the media library. See Media.
Site
These are mostly for headers, footers and the search page, but work anywhere.
| Kind (label) | Shows | Main settings |
|---|---|---|
site-name (Site name & logo) | the site name, a logo, or both, linking home | text (blank for the site name), tagline, media_id (logo), logo_height (CSS length), show_name (default on), href (default /) |
nav (Navigation) | the site navigation from published pages | direction (horizontal default, vertical), align, font_size (s, m, l, xl), weight (400 to 700), gap (s, m, l), show_home (default on), label (accessible name, default "Main") |
search-form (Search form) | a search box | placeholder, button_label, action (default /search), label |
social-links (Social links) | a row of links to profiles elsewhere | links of { label, href }, new_tab (default on); each link gets a plain link mark, no outside brand images |
copyright (Copyright) | "© 2026 holder. text" | holder (blank for the site name), show_year (default on), start_year (shows a range), text |
search-results (Search results) | what the current search found | prompt_text (before a search), empty_text (nothing matched), show_count (default on) |
The nav widget marks the link for the current page with the gsy-current class and aria-current="page".
Content
These show structured content in listing, single entry and term templates, and on an entry's own page. See Content types and entries.
| Kind (label) | Shows | Main settings |
|---|---|---|
entry-list (Entry list) | cards for the entries of a listing or term page | layout (grid default, list), count (default 48), show_image, show_excerpt, show_date, show_terms, image_ratio (3/2 default, 2/1, 16/9, 4/3, 1/1), source (a content type, so the list works on any page), columns 1 to 4, card_background, card_text, card_padding (s, m, l), card_corners (square), title_font (body), excerpt_lines, link_label, link_color, empty_text |
entry-title (Entry title) | the entry's title, or the term or type name on a listing | level (default 1), size, color, link (link to the entry) |
entry-field (Entry field) | one field of the entry | key (a field key, or excerpt or featured_image), label, tag (div or p), and for images size, aspect (16/9, 21/9, 9/4, 3/2, 4/3, 1/1) and overlay (darken, above 0 and up to 0.9); for text text_size and prose (muted) |
entry-fields (All fields) | every filled field of the entry, as label and value pairs in the type's order | skip (comma-separated keys) |
entry-meta (Date & terms) | the publication date and the entry's terms | show_date, show_terms (both default on), prefix, date_format (numeric for 01-01-2026), style (strong) |
term-list (Term list) | links to the term pages of a taxonomy, on listing and term pages | taxonomy (blank for all), direction, show_count, all_label (a first link back to the plain listing) |
breadcrumbs (Breadcrumbs) | on an entry, its listing then its title; elsewhere, home then the page title | home_label (default "Home"), show_home |
post-list (Post list) is the same renderer as entry-list under an older name, kept so existing documents still render.
Widgets from modules
Modules add their own widgets. They appear under Modules in the Add panel with the label and settings the module declares, and the inspector draws their inputs from that description. Writing one is covered in Content, widgets and templates.