Input field components

Components allow you to specify properties to define how a property will be displayed on the content form. For example, you can choose to display a number as a slider, allow text to be entered across multiple lines and control the way colors are chosen in the color picker.

This page contains the parameters for components that can be used for input fields and added to properties of type string, number, integer and boolean.

You an also specify some parameters for properties of type object and array.

Specifying property component parameters

To provide parameters to a component add the "ui:component" keyword to a property as shown below. In this example we have a string property that we want to display using the multi line text component.

You need to specify the component name together with the params. The component names are included on this page.

"properties":{
      "multiLineText":{
         "type":"string",
         "title":"Multi-line",
         "description":"Text area component",
         "ui:component":{
            "name":"text-area",
            "params":{
               "minRows":2,
               "maxRows":5
            }
         }
      }
   }

If you do not specify a component name, then the default component will be used for the property type, although you can still specify parameters.

Text

For properties of type string with no component name specified the default string component is used.

Parameters

Parameter	Description
placeholder	Initial guide text

Example

   "properties":{
      "singleLineString":{
         "type":"string",
         "title":"Single Line",
         "description":"Default component. Single line text",
         "ui:component":{
            "params":{
               "placeholder":"Some useful text"
            }
         }
      }
   }

Rich text (markdown)

A rich text component that supports markdown. Used with a property of type string and format markdown. You do not have to specify the component name.

Parameter	Description
defaultView	Whether the initial view should be the markdown or rich text editor. markdown or editor (default)
withMarkdownView	Is the markdown view shown. true (default) or false
withToolbar	Is the toolbar shown. true (default) or false

Example

"properties":{
      "richText":{
         "title":"Rich text",
         "type":"string",
         "format":"markdown",
         "ui:component":{
            "params":{
               "defaultView":"markdown"
            }
         }
      }
   }

Text area

A component that renders single or multi line text.

Parameters

Parameter	Description
name	text-area
minRow	Minimum number of rows for the text box
maxRow	Maximum number of rows for the text box
placeholder	Initial guide text
autosize	true or false. Specifies if the text area should grow with the content. false by default.

Example

   "properties":{
      "multiLineText":{
         "type":"string",
         "title":"Multi-line",
         "description":"Text area component",
         "ui:component":{
            "name":"text-area",
            "params":{
               "minRows":2,
               "maxRows":5,
               "placeholder":"Maximum of 5 lines will show before scroll",
               "autosize":"true"
            }
         }
      }
   }

Integer

For properties of type integer with no component name specified the default integer component is used. This is an editable text box with up and down arrows.

Parameters

Parameter	Description
suffix	String. Character added to the end of each number, for example degrees or percentage
defaultValue	The value used if there is no user input
allowNegative	true (default) or false. Should negative numbers be allowed
step	The increment used by the up and down arrows
variant	filled or unsettled
thousandSeparator	The string used to delimit thousands

Example

   "properties":{
      "percentValue":{
         "type":"integer",
         "title":"Percentage",
         "description":"Shows use of the suffix parameter",
         "examples":[
            "20%",
            "40%",
            "65%"
         ],
         "minimum":0,
         "maximum":100,
         "ui:component":{
            "params":{
               "placeholder":"50%",
               "variant":"filled",
               "suffix":"%",
               "allowNegative":false
            }
         }
      }
   }

Number

For properties of type number with no component name specified the default number component is used. This is an editable text box with up and down arrows.

Parameters

Parameter	Description
suffix	String. Character added to the end of each number, for example degrees or percentage
allowNegative	true (default) or false. Should negative numbers be allowed
step	The increment used by the up and down arrows
precision	The number of decimal places
variant	filled or unsettled
thousandSeparator	The string used to delimit thousands

Example

   "properties":{
      "number":{
         "type":"number",
         "title":"Number Temperature",
         "examples":[
            "2.5",
            "3.7"
         ],
         "minimum":-10,
         "maximum":10,
         "ui:component":{
            "params":{
               "suffix":"°",
               "defaultValue":-9.9,
               "allowNegative":true,
               "step":0.1,
               "precision":1
            }
         }
      }
   }

Dropdown list with labels

A component that shows a list of labels and values. The list is populated using the oneOf keyword and can be used with string, integer and number.

The title of each item is shown as the label in the list, while the value selected is defined by a const.

Parameters

Parameter	Description
searchable	true (default) or false . Determines whether the user can enter a value to search the list as well as scrolling

Example

"properties":{
      "labelledListWithDecimals":{
         "title":"Decimal dropdown with labels",
         "description":"A dropdown with user friendly labels",
         "type":"number",
         "oneOf":[
            {
               "title":"Low",
               "const":0.45
            },
            {
               "title":"Medium",
               "const":0.75
            },
            {
               "title":"High",
               "const":0.85
            }
         ]
      }
   }

Color

A color picker component. Used with a property of type string and format color.

Parameters

Parameter	Description
name	color
placeholder	Initial guide text
format	Color format. hex or RGBA. Hex is the default
colors	An array of colors. Displayed as swatches at the bottom of the picker
withPicker	true (default) or false. If set to false the user will only be able to choose a color from the swatches
withEyeDropper	true (default) or false. The eyeDropper tool is displayed on the right of the color input field and allows users to hover over and pick the color of any onscreen element
disallowInput	true or false (default). Set to true if you do not want the user to be able to input a color value

Example

   "properties":{
      "color":{
         "type":"string",
         "title":"Configurable color picker",
         "description":"Format is set to hex",
         "examples":[
            "#F88B8B",
            "#00E4B3",
            "#FFA980"
         ],
         "ui:component":{
            "name":"color",
            "params":{
               "placeholder":"Swatches are corporate colours",
               "format":"hex",
               "colors":[
                  "#F88B8B",
                  "#00E4B3",
                  "#FFA980",
                  "#216083",
                  "#B4C5F2",
                  "#F4F4F5"
               ]
            }
         }
      }
   }

Uri

A component that displays properties of type string and format uri. No name is specified so the default text component is used.

Parameters

Parameter	Description
placeholder	Initial guide text

Example

   "properties":{
      "uriString":{
         "type":"string",
         "title":"Web Address",
         "examples":[
            "https://amplience.com/developers/docs/",
            "https://amplience.com/developers/docs/schema-reference/validation/#text-format"
         ],
         "format":"uri",
         "ui:component":{
            "params":{
               "placeholder":"https://..."
            }
         }
      }
   }

Slider

A component for allowing integers and numbers to be entered using a slider. Used with properties of type integer or type number.

Parameters

Parameter	Description
name	slider
placeholder	Initial guide text
defaultValue	The initial value of the slider
inverted	true or false (default)
marks	Marks displayed along the slider. An array of value and label.
step	The amount the slider will be incremented using the thumb and arrows
px	Inline padding. xs, sm, md, lg or xl

Example

   "properties":{
      "sliderInteger":{
         "type":"integer",
         "description":"A slider with labels",
         "ui:component":{
            "name":"slider",
            "params":{
               "placeholder":"Some useful initial text",
               "defaultValue":75,
               "inverted":false,
               "marks":[
                  {
                     "value":0,
                     "label":"Transparent"
                  },
                  {
                     "value":25,
                     "label":"Faint"
                  },
                  {
                     "value":50,
                     "label":"Light"
                  },
                  {
                     "value":75,
                     "label":"Dark"
                  },
                  {
                     "value":100,
                     "label":"Solid"
                  }
               ],
               "step":25
            }
         }
      }
   }

Date-time

A component for representing a user selectable date and time. Used with a property of type string and format date-time.

Parameters

Parameter	Description
name	date-time
placeholder	Initial guide text

Example

   "properties":{
      "dateTime":{
         "type":"string",
         "title":"Date and Time field",
         "description":"User selectable date and time",
         "format":"date-time",
         "ui:component":{
            "params":{
               "placeholder":"Choose a date and time"
            }
         }
      }
   }

Date-time input

A component for allowing the user to enter a date and time using edit fields rather than a selectable date and time.

Parameters

Parameter	Description
name	date-time-input

Example

"properties": {
        "inputDateTime": {
            "type": "string",
            "title": "Date and Time input field",
            "description": "User editable date and time",
            "format": "date-time",
            "ui:component": {
                "name": "date-time-input"

            }
        }
    }

Date

A component for representing a user selectable date. Used with a property of type string and format date.

Parameters

Parameter	Description
name	date
placeholder	Initial guide text
valueFormat	The format shown of the date as shown in the form. For example: "MM-DD-YYYY". Note that this will not effect the JSON output which will always be of the form YYYY-MM-DD
defaultDate	The initial date. For example: "2015 March". Note this parameter does not currently work with the Apple Safari browser
defaultLevel	Set this to "year" to allow the user to initially choose the year, then the month and day. Note this parameter does not currently work with the Apple Safari browser

Example

   "properties":{
      "date":{
         "type":"string",
         "title":"Date field",
         "description":"User selectable date",
         "format":"date",
         "ui:component":{
            "params":{
               "placeholder":"Choose a date"
            }
         }
      }
   }

Time

A component for representing a user selectable time. Used with a property of type string and format time.

Parameters

Parameter	Description
name	time
placeholder	Initial guide text
pointer	Determines if a cursor pointer is shown. true or false (default)

Example

   "properties":{
      "time":{
         "type":"string",
         "title":"Time field",
         "description":"User selectable time component",
         "examples":[
            "00:00:01",
            "23:59:59"
         ],
         "format":"time",
         "ui:component":{
            "params":{
               "placeholder":"00:00:00",
               "pointer":false
            }
         }
      }
   }

Boolean

A checkbox component used for allowing the user a boolean selection.

Parameters

Parameter	Description
name	switch
labelPosition	left or right (default)

Example

   "properties":{
      "yesOrNoCheck":{
         "title":"Yes or no",
         "type":"boolean",
         "ui:component":{
            "name":"switch",
            "params":{
               "labelPosition":"left"
            }
         }
      }
   }

Objects

For complex properties that contain other properties, you can decide to hide the header, the title and description, to reduce the amount of space the property takes up.

You can also choose to set an object to be initially collapsed.

Parameters

Parameter	Description
collapsed	true or false (default). Is the property initially collapsed? This takes priority over default behaviour and the user setting for content.
withHeader	true (default) or false. Is the title and description shown for the top level item

Example

    "properties":{
      "contactDetails":{
         "title":"Contact details",
         "type":"object",
         "properties":{
            "name":{
               "title":"name",
               "description":"Full name",
               "type":"string"
            },
            "addressLine1":{
               "title":"address1",
               "description":"Street or building number",
               "type":"string"
            }
         },
         "ui:component":{
            "params":{
               "collapsed":true,
               "withHeader":false
            }
         }
      }
   }

Arrays

A list component with additional support for flexible lists of multiple types of content (content palettes).

Parameters

Parameter	Description
collapsed	true or false (default). Is the property initially collapsed? This takes priority over default behaviour and the user setting for content.
withChildHeaders	true or false (default). Set to true to hide the top level headers in the array
icons	Icons displayed in the selection menu for the content palette

Supported icons

Expand the section below to see the icons supported in a content palette.

Supported icons

Icon name	Icon
article
blockquote
carousel-horizontal
carousel-vertical
clock-hour-11
code
color-swatch
columns-2
columns-3
container
device-mobile
device-laptop
device-tablet
float-right
float-left
heading
html
layout
layout-bottombar
layout-grid
link
list
list-numbers
map-plus
music
numbers
photo-plus
plus
section
seo
separator
share
slideshow
square-plus
table-plus
template
text-caption
text-plus
typography
video-plus

Example: array without child headers

  "properties":{
      "arrayWithObject":{
         "type":"array",
         "items":{
            "type":"object",
            "properties":{
               "string":{
                  "type":"string"
               },
               "boolean":{
                  "type":"boolean"
               }
            }
         },
         "ui:component":{
            "params":{
               "withChildHeaders":false
            }
         }
      }
   }

Example: array with content palette

The following example shows a flexible list of content (a content palette) with text and banner objects. We've included params to configure the icons used for each object in the content palette menu selector. The icons map to the value of the const in the type property defined in each object.

If there are 3 or fewer items defined in the array then the user selects content using buttons, while more than 3 items are shown in a menu with the icons that you specify.

See the content palette schema reference and schema examples for more details.

{
  "properties": {
    "flexible-list": {
      "type": "array",
      "title": "Flexible list",
      "ui:component": {
        "params": {
          "icons": {
            "text": "typography",
            "banner": "carousel-horizontal"
          }
        }
      },
      "items": {
        "oneOf": [
          {
            "type": "object",
            "title": "Text",
            "properties": {
              "type": {
                "const": "text",
                "ui:component": "none"
              },
              "text": {
                "type": "string",
                "title": "Text",
                "maxLength": 200
              }
            }
          },
          {
            "type": "object",
            "title": "Banner",
            "properties": {
              "type": {
                "const": "banner",
                "ui:component": "none"
              },
              "title": {
                "type": "string",
                "title": "Title"
              },
              "image": {
                "title": "Image",
                "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
              },
              "titleColor": {
                "type": "string",
                "format": "color",
                "title": "Title Color"
              }
            }
          }
        ]
      }
    }
  }
}

Localized value set

This component allows you to choose the locales that are shown for a property. It is designed for use with field level localized properties.

Note that if the user filters out one of the pinned locales then a message will be displayed that a pinned property is hidden.

Parameters

Parameter	Description
name	localized-value-set
pinnedLocales	An array of locales that are initially shown for a property (eg en-US, fr-FR). Users may choose additional locales, but the pinned locales cannot be removed
withHeader	true (default) or false. Is the title and description shown for the top level item

Example: localized value with pinned locales

This example shows a localized text property with the locales of en-GB and fr-FR initially shown. Users will be able to choose additional locales, but the pinned locales will always be shown.

"properties":{
      "localizedString":{
         "title":"Localized String",
         "description":"Enter localized text",
         "allOf":[
            {
               "$ref":"http://bigcontent.io/cms/schema/v1/localization#/definitions/localized-string"
            }
         ],
         "ui:component":{
            "name":"localized-value-set",
            "params":{
               "pinnedLocales":[
                  "en-GB",
                  "fr-FR"
               ]
            }
         }
      }
}

Media card

The media card is used to display images and video with a title, description and optional alt text for images.

Parameters

Parameter	Description
withAltText	For images only. Should alt text metadata be shown on the card. true or false (default).

Example

The example shows an image property configured with alt text enabled.

"type": "object",
    "properties": {
        "image": {
            "title": "Image",
            "allOf": [
                { "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link" }
            ],
            "ui:component": {
                "params": {
                    "withAltText": true
                }
            }
        }