Widget Reference

import { Aside } from ‘@astrojs/starlight/components’;

Element structure

section/container          ← top level
  └─ column                ← only inside sections
       └─ widget
  └─ container (isInner)   ← only inside flexbox containers
       └─ widget

Every element needs id (8-char alphanumeric), elType, settings, elements (array, omit on widgets).

Section settings

{
  "id": "abc12345", "elType": "section",
  "settings": {
    "background_background": "classic",
    "background_color": "#FFFFFF",
    "padding": {"unit":"px","top":"70","right":"0","bottom":"70","left":"0","isLinked":false},
    "structure": "20"
  },
  "elements": []
}

Key	Values	Notes
`background_background`	`"classic"`, `"gradient"`	Required before `background_color`
`structure`	`"20"` (2-col), `"30"` (3-col), `"40"` (4-col)	Required for multi-column

Column _column_size values must sum to 100.

Free widgets

`heading`

{"title": "Page Title", "header_size": "h1", "align": "center", "title_color": "#0B1220"}

`text-editor`

{"editor": "<p>Rich HTML with <strong>bold</strong> and <a href='/'>links</a></p>"}

`html`

{"html": "<div style=\"text-align:center;\">Raw HTML</div>"}

`image`

{"image": {"url": "https://example.com/img.png", "id": 123}, "image_size": "full", "align": "center"}

`button`

{
  "text": "Click Me", "link": {"url": "/page/", "is_external": false},
  "align": "center", "size": "md",
  "background_color": "#1B4DFF", "button_text_color": "#FFFFFF",
  "border_radius": {"unit":"px","top":"8","right":"8","bottom":"8","left":"8","isLinked":true}
}

`icon-box`

{
  "selected_icon": {"value": "fas fa-check", "library": "fa-solid"},
  "title_text": "Feature Title", "description_text": "Description",
  "position": "left", "icon_color": "#1B4DFF",
  "title_typography_typography": "custom",
  "title_typography_font_size": {"unit": "px", "size": 18},
  "title_typography_font_weight": "600"
}

`accordion`

{
  "tabs": [
    {"tab_title": "Question 1?", "tab_content": "<p>Answer 1</p>"},
    {"tab_title": "Question 2?", "tab_content": "<p>Answer 2</p>"}
  ],
  "selected_icon": {"value": "fas fa-plus", "library": "fa-solid"},
  "selected_active_icon": {"value": "fas fa-minus", "library": "fa-solid"}
}

`counter`

{"starting_number": 0, "ending_number": 500, "suffix": "+", "title": "Happy Customers", "number_color": "#1B4DFF"}

`tabs`

{"tabs": [{"tab_title": "Tab 1", "tab_content": "<p>Content</p>"}], "type": "horizontal"}

`social-icons`

{
  "social_icon_list": [
    {"social_icon": {"value": "fab fa-twitter", "library": "fa-brands"}, "link": {"url": "https://twitter.com/..."}}
  ],
  "align": "center", "shape": "rounded"
}

`divider`

{"style": "solid", "weight": {"unit": "px", "size": 2}, "color": "#E2E8F0", "width": {"unit": "%", "size": 100}}

`spacer`

{"space": {"unit": "px", "size": 40}}

`star-rating`

{"rating_scale": 5, "rating": 4.5, "title": "Our Rating"}

Pro widgets

`flip-box`

{
  "title_text_a": "Front Title", "description_text_a": "Front description",
  "title_text_b": "Back Title", "description_text_b": "Back description",
  "button_text": "Click Me", "link": {"url": "/page/"},
  "graphic_element": "icon",
  "selected_icon": {"value": "fas fa-rocket", "library": "fa-solid"},
  "background_color_a": "#1B4DFF", "background_color_b": "#0B1220"
}

`animated-headline`

{
  "headline_style": "rotate", "animation_type": "typing",
  "before_text": "We build with",
  "rotating_text": "Claude\nChatGPT\nAI Assistants",
  "header_size": "h2", "align": "center"
}

animation_type: typing, clip, flip, swirl, blinds, drop-in, wave, slide

`price-table`

{
  "heading": "Pro Plan", "sub_heading": "Most Popular",
  "price": "49", "currency_symbol": "$", "period": "/month",
  "features_list": [
    {"item_text": "Unlimited pages", "selected_item_icon": {"value": "fas fa-check", "library": "fa-solid"}}
  ],
  "button_text": "Get Started", "link": {"url": "/pricing/"},
  "header_background_color": "#1B4DFF"
}

`form`

{
  "form_name": "Contact Form",
  "form_fields": [
    {"field_type": "text", "field_label": "Name", "required": "true", "width": "100"},
    {"field_type": "email", "field_label": "Email", "required": "true", "width": "100"},
    {"field_type": "textarea", "field_label": "Message", "required": "false", "width": "100"}
  ],
  "button_text": "Send Message", "email_to": "[email protected]"
}

`countdown`

{"countdown_type": "due_date", "due_date": "2026-12-31 23:59", "show_days": "yes", "show_hours": "yes", "show_minutes": "yes", "show_seconds": "yes"}

Theme builder widgets (Pro)

Widget	Key settings
`theme-post-title`	`title_tag`, `align`, `title_color`
`theme-post-content`	`align`
`theme-post-featured-image`	`image_size`, `align`, `link`
`theme-post-info`	`icon_list` array of `{type, icon}`
`theme-site-logo`	`width`, `align`
`theme-site-title`	`title_tag`, `link`
`theme-search-form`	`skin`, `placeholder`, `button_text`
`theme-archive-posts`	`columns`, `posts_per_page`, `show_excerpt`
`theme-builder-comments`	(no settings needed)

Typography pattern

{
  "{control}_typography_typography": "custom",
  "{control}_typography_font_family": "Inter",
  "{control}_typography_font_size": {"unit": "px", "size": 16},
  "{control}_typography_font_weight": "600",
  "{control}_typography_line_height": {"unit": "em", "size": 1.5}
}

{control} = title, description, button, etc.

Common pitfalls

Problem	Cause	Fix
Page blank	Invalid key crashes renderer	Check `warnings` in save response
Multi-column shows as single	Missing `structure` on section	Add `"structure": "20"` for 2-col
Flip-box shows defaults	Wrong key prefix	Use `title_text_a` / `title_text_b`
Widget not found	Typo in `widgetType`	Check “did you mean?” in response