Theme Schema Properties

The theme configuration object controls the visual appearance of a Formspace form, including colors, fonts, shadows, borders, and layout. Themes use the theme schema object and can include an advanced header configuration object.

Schema objects: theme, header

---

Theme Properties

themeName

• Type: string
• Default: "default"

A theme name. Formspace ships with several built-in themes (e.g. "default", "sharp", "borderless", "flat", "plain", "doubleborder", "layered", "solid", "threedimensional", "contrast").

colorPalette

• Type: string
• Default: "light"

A color palette. Possible values:

• "light" — Light color scheme.
• "dark" — Dark color scheme.

isPanelless

• Type: boolean
• Default: false

Specifies whether form questions are displayed within panels (false) or without them (true). When true, questions appear directly on the form background without individual panel containers.

backgroundImage

• Type: string
• Default: —

An image to display as form background. Accepts a hyperlink (URL) or a data URL (base64-encoded image).

backgroundImageFit

• Type: string
• Default: "cover"

Specifies how to resize the background image to fit its container. Possible values:

• "auto" — The image is displayed at its natural size.
• "contain" — Scales the image to the largest possible size without cropping.
• "cover" — Scales the image to the smallest possible size that fills the container, cropping if necessary.

See MDN background-size for details.

backgroundImageAttachment

• Type: string
• Default: "scroll"

Specifies whether the background image is fixed or scrolls with the form. Possible values:

• "fixed" — The image stays in place when the form is scrolled.
• "scroll" — The image scrolls along with the form content.

backgroundOpacity

• Type: number
• Default: 1

A value from 0 to 1 that specifies how transparent the background image should be. 0 makes the image completely transparent, and 1 makes it fully opaque.

headerView

• Type: string
• Default: "basic"

Specifies whether the form header uses basic or advanced appearance settings. Possible values:

• "basic" — Applies only the form title, description, and logo-related properties (logo, logoPosition, etc.).
• "advanced" — Applies the same properties as basic, plus advanced header settings from the header property of the theme. Features a more flexible layout, background image support, and other professional styling options.

header

• Type: header schema
• Default: —

An object with advanced form header settings. Only applies when headerView is set to "advanced". See the header schema Properties section below.

cssVariables

• Type: { [index: string]: string }
• Default: —

An object containing CSS custom properties (variables) that control the visual styling of the form. See Theme CSS Variables for common variable names and Theme Examples for ready-to-use theme objects.

---

Header Properties

The header schema interface configures advanced form header appearance. To use it, assign the object to the theme’s header property and set headerView to "advanced".

height

• Type: number
• Default: 256

The height of the form header in pixels.

mobileHeight

• Type: number
• Default: 0

The height of the form header on smartphones, measured in pixels. When set to 0, the height is calculated automatically to accommodate the header’s content.

inheritWidthFrom

• Type: string
• Default: "container"

Specifies whether the header spans the width of the form or the form container. Possible values:

• "survey" — The header width matches the form width.
• "container" — The header width matches the form container width.

textAreaWidth

• Type: number
• Default: 512

The width of the header area that contains the form title and description, measured in pixels.

overlapEnabled

• Type: boolean
• Default: false

Specifies whether the header overlaps the form content.

backgroundImage

• Type: string
• Default: —

An image to display in the background of the header. Accepts a base64 data URL or a regular URL string.

backgroundImageOpacity

• Type: number
• Default: 1

A value from 0 to 1 that specifies how transparent the header background image should be. 0 makes the image completely transparent, and 1 makes it fully opaque.

backgroundImageFit

• Type: string
• Default: "cover"

Specifies how to resize the header background image. Possible values:

• "cover" — Scales the image to the smallest possible size that fills the header, preserving aspect ratio but potentially cropping.
• "fill" — Stretches the image to fill the entire header (may distort).
• "contain" — Scales the image to the largest possible size without cropping or stretching.
• "tile" — Tiles as many copies of the image as needed to fill the header.

logoPositionX

• Type: string
• Default: "right"

The horizontal position of the logo within the header. Possible values: "left", "center", "right".

logoPositionY

• Type: string
• Default: "top"

The vertical position of the logo within the header. Possible values: "top", "middle", "bottom".

titlePositionX

• Type: string
• Default: "left"

The horizontal position of the form title within the header. Possible values: "left", "center", "right".

titlePositionY

• Type: string
• Default: "bottom"

The vertical position of the form title within the header. Possible values: "top", "middle", "bottom".

descriptionPositionX

• Type: string
• Default: "left"

The horizontal position of the form description within the header. Possible values: "left", "center", "right".

descriptionPositionY

• Type: string
• Default: "bottom"

The vertical position of the form description within the header. Possible values: "top", "middle", "bottom".

---

Related Theme References

• Theme CSS Variables - Common color, spacing, radius, border, shadow, and typography variables.
• Theme Examples - Brand color, panelless, advanced header, and default light theme examples.

Quick Theme Example

{
  "themeName": "default",
  "colorPalette": "light",
  "isPanelless": false,
  "cssVariables": {
    "--sjs-primary-backcolor": "rgba(37, 99, 235, 1)",
    "--sjs-primary-backcolor-light": "rgba(37, 99, 235, 0.1)",
    "--sjs-primary-backcolor-dark": "rgba(29, 78, 216, 1)",
    "--sjs-corner-radius": "8px"
  }
}