Parameters for components

Parameters are the elements that make up the component, such as a title, description, or image. They define the data that a component definition needs, which might be data in some external system or local parameters to influence how the external data appears when rendered.

For example, a promotion component might have two parameters:

• Content, which is a link to some content in a headless CMS
• Alignment, which could be a single select with text alignment options.

These are the basic building block of what will end up as component props when rendering a Canvas composition.

A parameter lets you set a value on a component. Each parameter has a type. The parameter type determines the kind of value you can set for the parameter.

Add a parameter#

1. In your project, navigate to Experience > Components and select your component.

2. Click the tab Parameters.

   

   Click to add a parameter.

3. Click the Add parameter button.

4. Select a base type for your parameter:

   

   Select a type of parameter to add to your component.

5. Configure the options for your parameter type. See parameter types below for reference.

   • Most parameter types can be made localizable so they store a different value for each locale
   • Most parameter types can enable conditional values which lets them store different values based on conditions such as dynamic inputs or quirks. Conditional values are only available to enterprise projects.

6. Click Save on the bottom of the dialog to update the component configuration. To add a new parameter you can also select Save and add another option in the button dropdown.

7. After all component updates are complete, make sure to save the component to apply your changes.

Parameter types#

The configuration options for each base parameter type differ. Each parameter type's options are outlined here.

Asset#

The asset parameter collects metadata-rich images and other media that may be stored in a data resource, an external asset library, or within Uniform's asset library. It also supports inline linking to external URLs. Learn about asset utilities provided by the Uniform SDK.

1. When adding an asset parameter, enter the following values:

   Name	Description	Notes
   Name	A text field to enter a descriptive name for the parameter or its purpose.
   Public ID	Name that uniquely identifies the parameter. This value is available to developers, and is auto generated from the Name given. It can't be changed once it's created.
   Help text	A user is responsible for setting a value on the parameter. This text appears below the user-interface available for setting the parameter value. The user interface for setting the value on a text parameter with help text set to 'Enter a short description of the event.' The help text in context of a composition.
   Required	Indicates whether setting an asset is required when the component is used. Default: false.
   Number of assets	Specify a minimum and maximum number of assets that can be added to the selection.
   Localizable	Allows the parameter to be localizable. If enabled, the default localization behavior can be set: Localized: One value can be set per locale Not localized: Singe value is used across all locales Editors can change the localization behavior on a per-instance basis.
   Allow conditional values	Set up multiple potential values and conditions for use. Learn more about conditional values.
   Use as display name	Setting this value to true will show the alt attribute of the first asset as the name of the component within the structure panel of a composition.
   Use as thumbnail	Setting this value to true will show the first asset as the thumbnail of the entry

2. Click Save on the bottom of the dialog to update the component configuration. To add a new parameter you can also select Save and add another option in the button dropdown.

3. After all component updates are complete, make sure to save the component to apply your changes.

Blocks#

Blocks are used to model repeated data within a component. They expect an array of data that's only shared in relation to something else. For example, on a site selling coffee beans you wouldn't present roasts or grind levels independent of the context of coffee beans. Learn about block utilities provided by the Uniform SDK.

Blocks differ from slots in that they're data or content focused, where slots are for nested or repeated UI components.

To add a block parameter to a component:

To add a block:

1. Create or navigate to the component to which you want to add a block at Experience > Components.

2. In the parameters section click Add parameter as described above.

3. Select Block from the list of field types.

4. Enter the following values:

   Name	Description	Notes
   Name	A text field to enter a descriptive name for the parameter or its purpose.
   Public ID	Name that uniquely identifies the parameter. This value is available to developers, and is auto generated from the Name given. It can't be changed once it's created.
   Help text	A user is responsible for setting a value on the parameter. This text appears below the user-interface available for setting the parameter value. The user interface for setting the value on a text parameter with help text set to 'Enter a short description of the event.' The help text in context of a composition.
   Required	Indicates whether setting a block is required when the component is used. Default: false.
   Number of blocks	Minimum: The minimum number of blocks to allow in the field. Maximum: The maximum number of blocks to allow in the field.
   Search for a type:	A field to select other content types to connect to the block field.	List of content types to connect to the block field.
   Allowed block types	A search field and available blocks are provided to find the block types you want to add. If you haven't yet created a block, you will see a message stating that there are no blocks created. You can add this field now, but it won't be useful until at least one block type is created and allowed in it.

Checkbox#

The checkbox parameter type has no configuration settings. It displays a checkbox for the user along with the Parameter Name value.

1. When adding a checkbox parameter, enter the following values:

   Name	Description
   Name	A text field to enter a descriptive name for the parameter or its purpose.
   Public ID	Name that uniquely identifies the parameter. This value is available to developers, and is auto generated from the Name given. It can't be changed once it's created.
   Help text	A user is responsible for setting a value on the parameter. This text appears below the user-interface available for setting the parameter value. The user interface for setting the value on a text parameter with help text set to 'Enter a short description of the event.' The help text in context of a composition.
   Localizable	Allows the parameter to be localizable. If enabled, the default localization behavior can be set: Localized: One value can be set per locale Not localized: Singe value is used across all locales Editors can change the localization behavior on a per-instance basis.
   Allow conditional values	Set up multiple potential values and conditions for use. Learn more about conditional values.

   How Uniform stores the value

   { "type": "checkbox", "value": true }

   CopyCopied!

2. Click Save on the bottom of the dialog to update the component configuration. To add a new parameter you can also select Save and add another option in the button dropdown.

3. After all component updates are complete, make sure to save the component to apply your changes.

Date#

The date parameter adds an area where authors can either enter a date (in mm/dd/yyyy format) or use a calendar selector to pick a date.

1. When adding an date parameter, enter the following values:

   Name	Description	Notes
   Name	A text field to enter a descriptive name for the parameter or its purpose.
   Public ID	Name that uniquely identifies the parameter. This value is available to developers, and is auto generated from the Name given. It can't be changed once it's created.
   Help text	A user is responsible for setting a value on the parameter. This text appears below the user-interface available for setting the parameter value. The user interface for setting the value on a text parameter with help text set to 'Enter a short description of the event.' The help text in context of a composition.
   Required	Indicates whether setting an date is required when the component is used. Default: false.
   No earlier than	Specify a date before which no author can set a value.
   No later than	Specify a date after which no author can set a value.
   Localizable	Allows the parameter to be localizable. If enabled, the default localization behavior can be set: Localized: One value can be set per locale Not localized: Singe value is used across all locales Editors can change the localization behavior on a per-instance basis.
   Allow conditional values	Set up multiple potential values and conditions for use. Learn more about conditional values.
   Use as display name	Setting this value to true will show what's entered in the Date field as the name of the component within the structure panel of a composition.

2. Click Save on the bottom of the dialog to update the component configuration. To add a new parameter you can also select Save and add another option in the button dropdown.

3. After all component updates are complete, make sure to save the component to apply your changes.

Date/Time#

The Date/Time parameter allows you to set a date and time in a specific timezone. The date and time are stored in the ISO 8601 format in UTC. Time zone names correspond to the tz database, such as America/New_York.

1. When adding an Date/Time parameter, enter the following values:

   Name	Description
   Name	A text field to enter a descriptive name for the parameter or its purpose.
   Public ID	Name that uniquely identifies the parameter. This value is available to developers, and is auto generated from the Name given. It can't be changed once it's created.
   Help text	A user is responsible for setting a value on the parameter. This text appears below the user-interface available for setting the parameter value. The user interface for setting the value on a text parameter with help text set to 'Enter a short description of the event.' The help text in context of a composition.
   Required	Indicates whether setting an date is required when the component is used. Default: false.
   Localizable	Allows the parameter to be localizable. If enabled, the default localization behavior can be set: Localized: One value can be set per locale Not localized: Singe value is used across all locales Editors can change the localization behavior on a per-instance basis.
   Allow conditional values	Set up multiple potential values and conditions for use. Learn more about conditional values.
   Use as display name	Setting this value to true will show what's entered in the Date/Time field as the name of the component within the structure panel of a composition.

2. Click Save on the bottom of the dialog to update the component configuration. To add a new parameter you can also select Save and add another option in the button dropdown.

3. After all component updates are complete, make sure to save the component to apply your changes.

Single select#

Lets a user select a single value from a list of options that are assigned to the parameter. It's used when you want to limit the options that are available to the user.

This parameter type has the following configuration settings:

1. When adding a Single select parameter, enter the following values:

   Name	Description
   Name	A text field to enter a descriptive name for the parameter or its purpose.
   Public ID	Name that uniquely identifies the parameter. This value is available to developers, and is auto generated from the Name given. It can't be changed once it's created.
   Help text	A user is responsible for setting a value on the parameter. This text appears below the user-interface available for setting the parameter value. The user interface for setting the value on a text parameter with help text set to 'Enter a short description of the event.' The help text in context of a composition.
   Options	The values that populate the select field. Click on the Add Option button to add a new option and specify the label text and value for it.
   Required	Indicates whether setting a link is required when the component is used. Default: false.
   Localizable	Allows the parameter to be localizable. If enabled, the default localization behavior can be set: Localized: One value can be set per locale Not localized: Singe value is used across all locales Editors can change the localization behavior on a per-instance basis.
   Allow conditional values	Set up multiple potential values and conditions for use. Learn more about conditional values.
   Use as display name	Setting this value to true will show what's selected in the Single select field as the name of the component within the structure panel of a composition.

   How Uniform stores the value

   { "type": "select", "value": "######################" }

   CopyCopied!

2. Click Save on the bottom of the dialog to update the component configuration. To add a new parameter you can also select Save and add another option in the button dropdown.

3. After all component updates are complete, make sure to save the component to apply your changes.

Multi select#

Lets a user select multiple values from a list of options that are assigned to the parameter. It's used when you want to limit the options that are available to the user.

This parameter type has the following configuration settings:

1. When adding a Multi select parameter, enter the following values:

   Name	Description
   Name	A text field to enter a descriptive name for the parameter or its purpose.
   Public ID	Name that uniquely identifies the parameter. This value is available to developers, and is auto generated from the Name given. It can't be changed once it's created.
   Help text	A user is responsible for setting a value on the parameter. This text appears below the user-interface available for setting the parameter value. The user interface for setting the value on a text parameter with help text set to 'Enter a short description of the event.' The help text in context of a composition.
   Options	The values that populate the select field. Click on the Add Option button to add a new option and specify the label text and value for it.
   Number of selections	Minimum: The minimum number of selections to allow in the parameter. Maximum: The maximum number of selections to allow in the parameter.
   Localizable	Allows the parameter to be localizable. If enabled, the default localization behavior can be set: Localized: One value can be set per locale Not localized: Singe value is used across all locales Editors can change the localization behavior on a per-instance basis.
   Allow conditional values	Set up multiple potential values and conditions for use. Learn more about conditional values.
   Use as display name	Setting this value to true will show what's selected in the Multi select field as the name of the component within the structure panel of a composition.

   How Uniform stores the value

   { "type": "multi-select", "value": [ "optionValue1", "optionValue2" ] }

   CopyCopied!

2. Click Save on the bottom of the dialog to update the component configuration. To add a new parameter you can also select Save and add another option in the button dropdown.

3. After all component updates are complete, make sure to save the component to apply your changes.

Image URL#

The image URL parameter provides a visual preview for an image URL. Images may be uploaded to the image URL parameter and stored by Uniform or an external URL may be used to add an inline link to an image.

1. When adding an image URL parameter, enter the following values:

   Name	Description	Notes
   Name	A text field to enter a descriptive name for the parameter or its purpose.
   Public ID	Name that uniquely identifies the parameter. This value is available to developers, and is auto generated from the Name given. It can't be changed once it's created.
   Help text	A user is responsible for setting a value on the parameter. This text appears below the user-interface available for setting the parameter value. The user interface for setting the value on a text parameter with help text set to 'Enter a short description of the event.' The help text in context of a composition.
   Required	Indicates whether setting an image URL is required when the component is used. Default: false.
   Validation Regex (optional)	Validation logic that limits the text the user can enter.	This uses the regular expression features in the user's browser.
   Validation Regex Message	Message displayed to the user when the input doesn't match the validation regex.	Only used if the validation regex is specified.
   Localizable	Allows the parameter to be localizable. If enabled, the default localization behavior can be set: Localized: One value can be set per locale Not localized: Singe value is used across all locales Editors can change the localization behavior on a per-instance basis.
   Allow conditional values	Set up multiple potential values and conditions for use. Learn more about conditional values.
   Use as display name	Setting this value to true will show what's entered in the Image URL field as the name of the component within the structure panel of a composition.

   How Uniform stores the value

   { "type": "image", "value": "https://my-website.dev/welcome.png" }

   CopyCopied!

   note

   Uniform doesn't optimize the image when rendered in Canvas. Try to keep the image file size as small as possible.

   Upload images to Uniform
   The Uniform image URL parameter always requires an image URL to function correctly. You can provide this directly from an image hosted in a remote source (such as a DAM, CMS or brand gallery), or Uniform can generate this URL for you through the upload utility.

   To upload an image, drag the image into the image URL parameter and Uniform will upload the image a Uniform server and automatically set the image URL. If you decide to change the image in the future, the previously uploaded image will be deleted. Uniform doesn't recommend copying and reusing image URLs from Uniform-hosted images across teams or projects.

   Uniform serves all Uniform-hosted images through a global CDN on the domain img.uniform.global to ensure fast load times.

   note

   The upload size limit is 10 MB per image.

2. Click Save on the bottom of the dialog to update the component configuration. To add a new parameter you can also select Save and add another option in the button dropdown.

3. After all component updates are complete, make sure to save the component to apply your changes.

JSON data#

The JSON data parameter lets you store any data that's serialized in valid JSON.

1. When adding a JSON parameter, enter the following values:

   Name	Description	Notes
   Name	A text field to enter a descriptive name for the parameter or its purpose.
   Public ID	Name that uniquely identifies the parameter. This value is available to developers, and is auto generated from the Name given. It can't be changed once it's created.
   Help text	A user is responsible for setting a value on the parameter. This text appears below the user-interface available for setting the parameter value. The user interface for setting the value on a text parameter with help text set to 'Enter a short description of the event.' The help text in context of a composition.
   Required	Indicates whether setting a link is required when the component is used. Default: false.
   Expected JSON schema	By providing a JSON schema you can provide validation rules to specify the expected shape and value types of the parameters JSON data. The JSON schema needs to follow the Draft 7 specification.
   Localizable	Allows the parameter to be localizable. If enabled, the default localization behavior can be set: Localized: One value can be set per locale Not localized: Singe value is used across all locales Editors can change the localization behavior on a per-instance basis.
   Allow conditional values	Set up multiple potential values and conditions for use. Learn more about conditional values.
   Use as display name	Setting this value to true will extrapolate a value from the JSON data entered as the name of the component within the structure panel of a composition.

   { "type": "object", "required": ["name", "sku"], "properties": { "name": { "type": "string" }, "sku": { "type": "string" }, "description": { "type": "string" }, "price": { "type": "number" }, "currency": { "type": "string" } }, "description": "A simple product schema" }

   CopyCopied!

   How Uniform stores the value

   { "type": "json", "value": { /* any JSON data */ } }

   CopyCopied!

2. Click Save on the bottom of the dialog to update the component configuration. To add a new parameter you can also select Save and add another option in the button dropdown.

3. After all component updates are complete, make sure to save the component to apply your changes.

Link#

The link parameter lets a user create a link to a node in a project map, or simple static URL, or email address or telephone number.

In the case of project map, the link will automatically update when the path of the node is updated by moving the node to another location in the node tree.

1. When adding a link parameter, enter the following values:

   Name	Description
   Name	A text field to enter a descriptive name for the parameter or its purpose.
   Public ID	Name that uniquely identifies the parameter. This value is available to developers, and is auto generated from the Name given. It can't be changed once it's created.
   Help text	A user is responsible for setting a value on the parameter. This text appears below the user-interface available for setting the parameter value. The user interface for setting the value on a text parameter with help text set to 'Enter a short description of the event.' The help text in context of a composition.
   Types of links	Types of link you can configure in the parameter: Project map, URL, Email address, Telephone number. By default all types are enabled.
   Localizable	Allows the parameter to be localizable. If enabled, the default localization behavior can be set: Localized: One value can be set per locale Not localized: Singe value is used across all locales Editors can change the localization behavior on a per-instance basis.
   Allow conditional values	Set up multiple potential values and conditions for use. Learn more about conditional values.
   Use as display name	Setting this value to true will show what's entered in the Link field as the name of the component within the structure panel of a composition. If a project map node is the type of link, an ID will be shown.

   How Uniform stores the value: Project map

   { "type": "link", "value": { "type": "projectMapNode", "path": "/path/of/node", "nodeId": "<some-id-value>", "projectMapId": "<some-id-value>" } }

   CopyCopied!

   How Uniform stores the value: Url, email address, or telephone number

   { "type": "link", "value": { "type": "url", // or "email" or "tel" "path": "https://localhost:3000", // or "address@gmail.com" or "+45 88 88 88 88" } }

   CopyCopied!

   How to render in React using the HREF attribute

   const CtaButton = ({ label, link }) => { let href = link.path; if (link.type === 'tel') { href = `tel:${href}`; } else if (link.type === 'email') { href = `mailto:${href}`; } return ( <a href={href}>{label}</> ); }

   CopyCopied!

   Learn more about the HREF attribute.

2. Click Save on the bottom of the dialog to update the component configuration. To add a new parameter you can also select Save and add another option in the button dropdown.

3. After all component updates are complete, make sure to save the component to apply your changes.

Number#

The number parameter lets a user enter a numeric value.

1. When adding a number parameter, enter the following values:

   Name	Description	Notes
   Name	A text field to enter a descriptive name for the parameter or its purpose.
   Public ID	Name that uniquely identifies the parameter. This value is available to developers, and is auto generated from the Name given. It can't be changed once it's created.
   Help text	A user is responsible for setting a value on the parameter. This text appears below the user-interface available for setting the parameter value. The user interface for setting the value on a text parameter with help text set to 'Enter a short description of the event.' The help text in context of a composition.
   Required	Indicates whether setting a number is required when the component is used. Default: false.
   Integer	Use this when the number is a whole number (such as 3, 17, 101, 5000).	Radio button
   Decimal	Use this when the number is a fractional number (such as 12.44, 400.00, 1044.80).	Radio button
   Number of decimal places	This controls how precise a number can the user enter.	This option is only available for decimal numbers.
   Minimum	The user can't enter a value less than this.	Optional
   Maximum	The user can't enter a value greater than this.	Optional
   Localizable	Allows the parameter to be localizable. If enabled, the default localization behavior can be set: Localized: One value can be set per locale Not localized: Singe value is used across all locales Editors can change the localization behavior on a per-instance basis.
   Allow conditional values	Set up multiple potential values and conditions for use. Learn more about conditional values.
   Use as display name	Setting this value to true will show what's entered in the Number field as the name of the component within the structure panel of a composition.

   How Uniform stores the value

   { "type": "number", "value": "####.##" }

   CopyCopied!

   tip

   Notice that the value is stored as a string, not as a number.

2. Click Save on the bottom of the dialog to update the component configuration. To add a new parameter you can also select Save and add another option in the button dropdown.

3. After all component updates are complete, make sure to save the component to apply your changes.

Rich text#

With the rich text parameter, users can apply various formatting options such as heading levels, bold, italics, underline, strike through, and more to emphasize specific words or phrases. Additionally, it supports the inclusion of hyperlinks (both static and project map), bullet points, numbered lists, tables, and dynamic tokens.

1. When adding a rich text parameter, enter the following values:

   Name	Description	Required
   Name	A text field to enter a descriptive name for the parameter or its purpose.
   Public ID	Name that uniquely identifies the parameter. This value is available to developers, and is auto generated from the Name given. It can't be changed once it's created.
   Help text	A user is responsible for setting a value on the parameter. This text appears below the user-interface available for setting the parameter value. The user interface for setting the value on a text parameter with help text set to 'Enter a short description of the event.' The help text in context of a composition.
   Required	Indicates whether setting a link is required when the component is used. Default: false.
   Allowed controls	Controls which formatting and element options are available to users. By default all options are enabled. The allowed controls available in rich text.
   Localizable	Allows the parameter to be localizable. If enabled, the default localization behavior can be set: Localized: One value can be set per locale Not localized: Singe value is used across all locales Editors can change the localization behavior on a per-instance basis.
   Allow conditional values	Set up multiple potential values and conditions for use. Learn more about conditional values.
   Use as display name	Setting this value to true will show what's entered in the Rich text field as the name of the component within the structure panel of a composition.

   How Uniform stores the value

   { "type": "richText", "value": { "root": { "type": "root", "children": [] } } }

   CopyCopied!

2. Click Save on the bottom of the dialog to update the component configuration. To add a new parameter you can also select Save and add another option in the button dropdown.

3. After all component updates are complete, make sure to save the component to apply your changes.

Text#

The text parameter lets a user enter a text value.

1. When adding a text parameter, enter the following values:

   Name	Description	Notes
   Name	A text field to enter a descriptive name for the parameter or its purpose.
   Public ID	Name that uniquely identifies the parameter. This value is available to developers, and is auto generated from the Name given. It can't be changed once it's created.
   Help text	A user is responsible for setting a value on the parameter. This text appears below the user-interface available for setting the parameter value. The user interface for setting the value on a text parameter with help text set to 'Enter a short description of the event.' The help text in context of a composition.
   Required	Indicates whether the value is required when the component is used.
   Allow multi-line text	If selected, the user enters the text into a multi-line text box.	Multi-line text is saved in a string with the line-break character \n used to separate lines.
   Lines count	Maximum number of lines of text the user can enter.	Only available when the allow multi-line text option is enabled.
   Validation Regex (optional)	Validation logic that limits the text the user can enter.	This uses the regular expression features in the user's browser.
   Test	If a value is entered it's checked against the validation regex.
   Validation Regex Message	Message displayed to the user when the input doesn't match the validation regex.	Only used if the validation regex is specified.
   Localizable	Allows the parameter to be localizable. If enabled, the default localization behavior can be set: Localized: One value can be set per locale Not localized: Singe value is used across all locales Editors can change the localization behavior on a per-instance basis.
   Allow conditional values	Set up multiple potential values and conditions for use. Learn more about conditional values.
   Use as display name	Setting this value to true will show what's entered in the Text field as the name of the component within the structure panel of a composition.

   How Uniform stores the value

   { "type": "text", "value": "######################" }

   CopyCopied!

Custom parameters#

It is possible to implement your own custom parameter visuals, validation, and data formats using custom integrations.

Group parameters#

Component parameters may be grouped to help cluster related ideas together in the Canvas editor. For example, you may collect fields for meta title and meta description in a group called "Meta data."

Parameters grouped in a component.

1. To create a parameter group, navigate to Experience > Components and select the appropriate component in your project.

2. Click the tab Parameters.

3. Click the chevron on the Add parameter button to open the menu

4. Select “Add parameter group”

5. Enter the following values:

   Field	Description
   Name	The group name will be displayed in the canvas editor. it's the only label visible when the group is collapsed.
   Is collapsed by default?	If checked, the group will be collapsed by default. If unchecked, it will be expanded by default. Editors can always expand or collapse the group in the canvas editor. Default: checked

6. Click OK to save your changes.

7. Click Save to save the changes to the component.

   

   A group of parameters in the parameter view of a component.

8. Parameters can be added to the group by dragging and dropping them into the group. Groups can also be rearranged in the same way. The order shown in the table is the order they will be displayed in the Canvas editor.

Delete a parameter#

1. In your project, navigate to Experience > Components and select your component.

2. Click the tab Parameters.

   

   The parameters tab on the component page.

3. Click > Delete.

4. Click Save to save the changes to the component.

Orphan parameter warning.