Widget Settings Fields

Widget settings fields allow Staffbase administrators to configure your custom widget without touching code. Each field you define appears in the Staffbase widget settings panel when an admin adds your widget to a page.

Field values are accessible in your Handlebars layout template via {{settings.propName}}.

Common Properties

Every field type shares the following configuration options:

Property	Type	Required	Description
Label	`string`	Yes	Display name shown to the admin in the settings panel.
Property Name	`string`	Yes	Internal identifier used in templates. Must contain only letters, numbers, hyphens, and underscores (`A-Za-z0-9-_`). Auto-generated from the label when creating a new field.
Required	`boolean`	No	Whether the admin must provide a value. Defaults to `false`.

Naming convention

Use descriptive, camelCase or snake_case property names. The property name is auto-generated from the label (spaces become underscores, special characters are removed, German umlauts are transliterated). You can always edit it manually.

Field Types

Text

A single-line text input for short string values.

Property	Details
Field identifier	`text`
Data type	`string`
Default value	Optional. Any string. Falls back to empty string `""`.

Template usage:

<h2>{{settings.headline}}</h2>
<a href="{{settings.link_url}}">Read more</a>

Best for: Titles, URLs, short labels, single-line content.

Number

A numeric input that only accepts number values.

Property	Details
Field identifier	`number`
Data type	`number`
Default value	Optional. Any number. Falls back to `0`.

Template usage:

<div style="padding: {{settings.spacing}}px;">
  Showing
  {{settings.item_count}}
  items
</div>

Best for: Counts, sizes, spacing values, numeric thresholds.

Textarea

A multi-line text input for longer content.

Property	Details
Field identifier	`textarea`
Data type	`string`
Default value	Optional. Any string (supports line breaks). Falls back to empty string `""`.

Template usage:

<p>{{settings.description}}</p>

Best for: Descriptions, paragraphs, HTML snippets, CSS overrides, JSON configuration.

Checkbox

A boolean toggle (rendered as a true/false dropdown in the settings panel).

Property	Details
Field identifier	`checkbox`
Data type	`boolean`
Default value	`true` or `false`. Falls back to `false`.

Template usage:

{{#if settings.show_header}}
  <header>Welcome!</header>
{{/if}}

Best for: Feature toggles, show/hide flags, on/off switches.

A single-select dropdown menu with predefined options.

Property	Details
Field identifier	`dropdown`
Data type	`string`
Default value	Optional. Must be one of the defined options. Falls back to the first option.
Options	Required. A list of values, one per line. Duplicate values are automatically removed.

Template usage:

<div class="theme-{{settings.color_theme}}">
  {{#if (eq settings.layout "grid")}}
    <!-- grid layout -->
  {{else}}
    <!-- list layout -->
  {{/if}}
</div>

Best for: Theme selection, layout modes, predefined categories, any "pick one from a list" scenario.

Adding options

When configuring a dropdown field, enter each option on a separate line in the options textarea. The first option becomes the default if no explicit default is set.

Radio

A radio button group with predefined options. Functionally identical to Dropdown but rendered as radio buttons in the Staffbase settings panel.

Property	Details
Field identifier	`radio`
Data type	`string`
Default value	Optional. Must be one of the defined options. Falls back to the first option.
Options	Required. A list of values, one per line. Duplicate values are automatically removed.

Template usage:

<div class="align-{{settings.text_alignment}}">
  {{settings.content}}
</div>

Best for: Small sets of options (2-4 choices) where all options should be visible at once.

Date

A date picker input.

Property	Details
Field identifier	`date`
Data type	`string`
Default value	Optional. ISO date string (e.g. `2024-01-15`). Falls back to empty string `""`.

Template usage:

<p>Event date: {{settings.event_date}}</p>

Best for: Event dates, deadlines, publication dates.

Time

A time picker input.

Property	Details
Field identifier	`time`
Data type	`string`
Default value	Optional. Time string (e.g. `14:30`). Falls back to empty string `""`.

Template usage:

<p>Starts at {{settings.start_time}}</p>

Best for: Opening hours, event times, schedule entries.

Date & Time

A combined date and time picker.

Property	Details
Field identifier	`datetime`
Data type	`string`
Default value	Optional. ISO datetime string (e.g. `2024-01-15T14:30:00`). Falls back to empty string `""`.

Template usage:

<time datetime="{{settings.event_start}}">{{settings.event_start}}</time>

Best for: Event timestamps, deadlines with specific times.

URL

A text input validated as a URL.

Property	Details
Field identifier	`url`
Data type	`string`
Default value	Optional. A valid URL (e.g. `https://example.com`). Falls back to empty string `""`.

Template usage:

<a href="{{settings.website_url}}">Visit website</a>
<img src="{{settings.image_url}}" alt="Custom image" />

Best for: Links, image sources, API endpoints.

Email

A text input validated as an email address.

Property	Details
Field identifier	`email`
Data type	`string`
Default value	Optional. A valid email address. Falls back to empty string `""`.

Template usage:

<a href="mailto:{{settings.contact_email}}">Contact us</a>

Best for: Contact emails, notification recipients.

Color

A color picker that stores a hex color value.

Property	Details
Field identifier	`color`
Data type	`string`
Default value	Optional. A hex color (e.g. `#ff0000`). Falls back to `#000000`.

Template usage:

<div
  style="background-color: {{settings.brand_color}}; color: {{settings.text_color}};"
>
  Styled content
</div>

Best for: Brand colors, background colors, accent colors, theme customization.

Slider

A range slider for selecting a numeric value within a defined range.

Property	Details
Field identifier	`slider`
Data type	`number`
Default value	Optional. A number within the min/max range. Falls back to the `min` value.
Min	Required. Minimum value of the range.
Max	Required. Maximum value of the range.
Step	Optional. Increment step size.

Template usage:

<div style="opacity: {{settings.opacity}};">
  Content with adjustable opacity
</div>

Best for: Opacity, spacing, font sizes, any bounded numeric value.

Rating

A star-rating input for selecting a value from 1 to a configurable maximum.

Property	Details
Field identifier	`rating`
Data type	`integer`
Default value	Optional. An integer between 1 and `max`. Falls back to `1`.
Max Stars	Optional. Maximum number of stars (1–10). Defaults to `5`.

Template usage:

<div class="rating">
  {{#each (times settings.importance)}}★{{/each}}
</div>

{{#if (gte settings.priority 4)}}
  <span class="badge">High Priority</span>
{{/if}}

Best for: Priority levels, importance ratings, quality scores, satisfaction levels.

Location (Geo)

A location picker with address search and geolocation support. The value is stored as a JSON string containing the address, latitude, and longitude.

Property	Details
Field identifier	`geo`
Data type	`string` (JSON)
Default value	Optional. A JSON string (e.g. `{"address":"Berlin, Germany","lat":52.52,"lng":13.405}`). When a default address is provided in the builder, it is geocoded automatically. Falls back to empty string `""`.

Stored value format:

The geo field stores its value as a JSON string with three properties:

{
  "address": "Berlin, Germany",
  "lat": 52.52,
  "lng": 13.405
}

JSON Property	Type	Description
`address`	`string`	Human-readable address from OpenStreetMap
`lat`	`number`	Latitude coordinate
`lng`	`number`	Longitude coordinate

Template usage:

To use individual properties, parse the JSON value with the json helper:

{{#with (json settings.location)}}
  <p>📍 {{address}}</p>
  <p>Coordinates: {{lat}}, {{lng}}</p>
  <a href="https://www.google.com/maps?q={{lat}},{{lng}}" target="_blank">
    View on Google Maps
  </a>
{{/with}}

You can also use the raw JSON string directly if needed:

<div data-location="{{settings.location}}">Map widget</div>

Admin experience: The settings panel shows an address search field (powered by OpenStreetMap) and a "Use my location" button. Once a location is selected, the resolved address and coordinates are displayed.

Best for: Store locations, event venues, office addresses, points of interest.

Staffbase Items

An autocomplete search field that lets admins select Staffbase platform resources (users, channels, pages, spaces, or groups). Supports single and multi-select. The value is stored as a JSON array of selected items.

Property	Details
Field identifier	`staffbase-items`
Data type	`string` (JSON)
Default value	Optional. Selected via autocomplete in the Widget Builder. Falls back to empty string `""`.
Item Type	Required. The Staffbase resource to search: `users`, `channels`, `pages`, `spaces`, or `groups`.
Multiple	Optional. When enabled, admins can select multiple items. Defaults to `false` (single select).

Stored value format:

When Multiple is enabled, the field stores a JSON array:

[
  { "id": "abc123", "name": "Anna Schmidt", "type": "users" },
  { "id": "def456", "name": "Max Mueller", "type": "users" }
]

When Multiple is disabled (single select), the field stores a single JSON object:

{ "id": "abc123", "name": "Anna Schmidt", "type": "users" }

JSON Property	Type	Description
`id`	`string`	Staffbase resource ID
`name`	`string`	Display name (user full name, channel title, etc.)
`type`	`string`	Resource type (`users`, `channels`, `pages`, `spaces`, `groups`)

Template usage:

To iterate over selected items, parse the JSON value with the json helper:

{{#each (json settings.selected_users)}}
  <div class="user-card">
    <p>{{name}} ({{id}})</p>
  </div>
{{/each}}

For a single-select field, the value is already a single object:

{{#with (json settings.assigned_user)}}
  <p>Assigned to: {{name}}</p>
{{/with}}

Admin experience:

The settings panel shows an autocomplete search input. Typing searches the Staffbase platform API in real-time. Clicking the dropdown chevron loads the first 10 items for browsing.

Staffbase Items autocomplete dropdown showing search results

Selected items appear as dismissible tags above the input. In single-select mode, the input is hidden after a selection is made.

Staffbase Items with selected users shown as tags >

Error handling:

The widget shows inline error messages for authentication (401), permission (403), and bad request (400) errors.

Best for: Assigning users, linking to channels or pages, selecting target groups or spaces.

Using Fields in Templates

All field values are available under the settings object in your Handlebars templates:

<!-- Direct value output -->
<h1>{{settings.title}}</h1>

<!-- Conditional rendering with checkbox -->
{{#if settings.show_footer}}
  <footer>{{settings.footer_text}}</footer>
{{/if}}

<!-- Using in attributes -->
<div
  style="background-color: {{settings.bg_color}}; padding: {{settings.padding}}px;"
>
  {{settings.content}}
</div>

<!-- Using in API proxy URLs -->
<!-- See the API Proxy guide for details -->

Best Practices

Use clear labels -- The label is what Staffbase admins see. Make it descriptive enough that the purpose is obvious without additional context.
Set sensible defaults -- Always provide a default value so the widget looks good without configuration.
Choose meaningful property names -- Property names appear in your template code. Use names that make the template readable (e.g., show_header instead of flag1).
Prefer Dropdown over Radio for long lists -- Radio buttons work best for 2-4 options. For longer lists, use a Dropdown.
Use Checkbox for boolean logic -- If a setting is on/off, use Checkbox rather than a Dropdown with "Yes"/"No" options.
Keep property names stable -- Changing a property name after the widget is published will break existing widget instances that rely on the old name.

Common Properties​

Field Types​

Text​

Number​

Textarea​

Checkbox​

Dropdown​

Radio​

Date​

Time​

Date & Time​

URL​

Email​

Color​

Slider​

Rating​

Location (Geo)​

Staffbase Items​

Using Fields in Templates​

Best Practices​

Common Properties

Field Types

Text

Number

Textarea

Checkbox

Dropdown

Radio

Date

Time

Date & Time

URL

Email

Color

Slider

Rating

Location (Geo)

Staffbase Items

Using Fields in Templates

Best Practices