At a bare minimum you'll want to include PDF images for light mode icons so they can be used for all views where your Component appears within the RapidWeaver Elements UI.

Standard Icon

All Elements require an icon.pdf file for light mode. If the dark-mode.pdf file isn't provided, icon.pdf will be used in Dark Mode.

• icon.pdf (Required), 1:1 ratio, e.g. 128x128 (Square)

• icon-dark.pdf (optional), 1:1 ratio, e.g. 128x128 (Square)

Palette Icons

The Palette image should be named paletteIcon.pdf and paletteIcon-dark.pdf for Dark Mode. If the paletteIcon-dark.pdf file isn't provided, paletteIcon.pdf will be used in Dark Mode.

• paletteIcon.pdf (Required), 1:2 ratio, e.g. 128x256 (landscape)

• paletteIcon-dark.pdf (optional), 1:2 ratio, e.g. 128x256 (landscape)

Asset Placement

All Icon files should be placed at the root of the Component alongside the info.json file.

How to add a Custom Icon to your Component

Watch the short video below to learn more about adding custom icons to your Components.

Sketch Example File

Your pdf icons MUST be on a transparent background. The background should not be exported as this is generated in Elements.

We've provided an example Sketch document below you can use to get started.

Experimental / Unsupported - Banner Icons

There is some unfinished experimental support for banner style icons, these are great for layout style components. However, this style of icon may not be supported when Elements ships, please use with caution and ensure you also include the standard style of icon.

• bannerLayer1.png

• bannerLayer1-Dark.png (optional)

Banner icons can be layered, and each layer can represent a different colour in the Theme Studio. For example this icon uses four layers and three of those layers will be tinted with the Theme colour.

• bannerLayer1.png

• bannerLayer2-brand-500.png

• bannerLayer3-brand-200.png

• bannerLayer4-surface-500.png

Banner images should be 512px in width, but can be as short or tall as you need. Banner icons will appear the same in both grid and list.

The visible key in an object's properties can be set using a logical expression that evaluates to true or false. This determines whether a specific UI element is shown or hidden based on the conditions specified in the expression. Works in the same way as enabled.

• Boolean Logic: Use logical operators (&&, ||) to combine multiple conditions.

• Comparison Operators: Use ==, !=, >, <, >=, <= to compare values.

Examples

1. Complex Condition

   Copy

   "visible": "(backgroundType == 'custom' || backgroundType == 'image') && textColor == 'white'"

   This makes the property visible only if the backgroundType is either custom' or 'image', and the textColor is 'white'.

2. Visibility Based on Numeric Ranges

   Copy

   "visible": "opacity > 20 && opacity < 30"

   Useful for showing elements that should only be visible within a specific range, e.g., showing a message if the opacity is not between 20-30.

3. Negation to Hide Elements

   Copy

   "visible": "mySwitchControl != true"

   The property is visible when mySwitchControl is false.

The following example code toggles the visibility of controls based on the value of the switch.

{
    "groups": [{
        "title": "SWITCH TEST",
        "icon": "switch.2",
        "properties": [{
            "title": "Test Switch",
            "id": "testSwitch",
            "responsive": false,
            "switch": {
                "default": false
            }
        }, {
            "information": {},
            "title": "No Controls",
            "visible": "testSwitch == false"
        }, {
            "information": {},
            "title": "Let's Slide…",
            "visible": "testSwitch == true"
        }, {
            "title": "slider",
            "id": "slider",
            "visible": "testSwitch != false",
            "slider": {
                "default": 5,
                "min": 1,
                "max": 50,
                "round": true
            }
        }]
    }]
}

Groups allow you to organise similar settings into relevant groups.

Here is an example emtpy group:

{
	"groups": [
			{
	  "title": "Untitled",
	  "icon": "paintpalette",
	  "properties": [
		  
		]
	}]
}

Controls should placed inside of the properties array. The following example has a heading and an image drop well inside of the group.

{
    "groups": [
        {
            "title": "Button Design",
            "icon": "paintpalette",
            "properties": [
                {
                    "title": "Title",
                    "id": "buttonTitle",
                    "default": "",
                    "text": {
                       "default": "Click Me"
                    }
                },
                {
                    "title": "Image",
                    "id": "buttonImage",
                    "image": {}
                },
                
            ]
        }
    ]
}

The following example has two groups, the first with a text box, and the second with an image dropwell.

{
    "groups": [{
        "title" : "First Group",
        "icon" : "1.circle.fill",
        "properties" : [{
            "title": "Title",
            "id": "title",
            "text": {}
        }]
    },
    {
        "title" : "Second Group",
        "icon" : "2.circle.fill",
        "properties" : [{
            "title": "Image",
            "id": "image",
            "image": {}
        }]
    } 
    ]
}

All properties have the same general structure using the following object keys.

Code Example

Responsive Values

By default, Elements makes all property controls responsive, allowing users to override any control setting across different devices. Elements accomplishes this by appending Tailwind’s responsive modifiers to the control’s value. Let’s explore how this works in an example.

Responsive Example

In this example, a control uses Tailwind’s text transform utility classes. The user can customize the control’s value across devices by clicking the responsive icon (dot) next to the control title in Elements.

Initially, the headingTextTransform output is set to normal-case. However, once the user customizes this setting in Elements, it may look something like this: normal-case sm:uppercase md:lowercase lg:capitalize.

Elements automatically applies and manages these responsive modifiers, saving you the effort of manually setting values for each device size and applying the appropriate modifier.

Multi Value Responsive

This even works for controls that require multiple classes as the value. So given the following control:

You can expect the output of position to be bottom-0 left-0 right-auto md:top-0 md:left-auto md: right-0

Disable Responsive Controls

To disable responsive values for your control, simply add "responsive": false to your control.

The info.json file contains important information about a Component. The file uses the JSON format and consists of a series of key and value pairs. It's required for Component to function.

Component Categories

Every Component needs to define a category in which they belong. This tells Elements how to group components in the UI and helps users to locate components. Your Component MUST use one of the following pre-defined categories.

If you think we're missing a category, please visit the .

Supported Key-Value Pairs

The Elements info.json file supports the following key-value pairs.

info.json Example

You can use the following code as a starting point for your own info.json file.

Displays a select box, also known as a dropdown menu.

{
    "title": "Case",
    "id": "headingTextTransform",
    "select": {
        "default": "normal-case",
        "items": [{
            "value": "normal-case",
            "title": "None"
        }, {
            "value": "uppercase",
            "title": "Uppercase"
        }, {
            "value": "lowercase",
            "title": "Lowercase"
        }, {
            "value": "capitalize",
            "title": "Capitalize"
        }]
    }
}

{
    "groups": [{
        "title": "Select Example",
        "properties": [{
            "title": "Case",
            "id": "headingTextTransform",
            "select": {
                "default": "normal-case",
                "items": [{
                    "value": "normal-case",
                    "title": "None"
                }, {
                    "value": "uppercase",
                    "title": "Uppercase"
                }, {
                    "value": "lowercase",
                    "title": "Lowercase"
                }, {
                    "value": "capitalize",
                    "title": "Capitalize"
                }]
            }
        }]
    }]
}

Display a divider between content.

{
    "divider": {}
}

{
    "groups": [{
        "title": "Divider Example",
        "properties": [{
            "divider": {}
        }]
    }]
}

The enabled key in an object's properties can be set using a logical expression that evaluates to true or false. This determines whether a specific UI element is enabled or disabled based on the conditions specified in the expression. Works in the same way as visible.

• Boolean Logic: Use logical operators (&&, ||) to combine multiple conditions.

• Comparison Operators: Use ==, !=, >, <, >=, <= to compare values.

Examples

1. Complex Condition

   Copy

   "enabled": "(backgroundType == 'custom' || backgroundType == 'image') && textColor == 'white'"

   This makes the property enabled only if the backgroundType is either custom' or 'image', and the textColor is 'white'.

2. Visibility Based on Numeric Ranges

   Copy

   "enabled": "opacity > 20 && opacity < 30"

   Useful for enabling controls that should only be visible within a specific range.

3. Negation to Hide Elements

   Copy

   "enabled": "mySwitchControl != true"

   The property is enabled when mySwitchControl is false.

Displays a heading in the inspector interface.

{
    "title": "Border",
    "heading": {}
}

{
    "groups": [{
        "title": "Heading Example",
        "properties": [{
            "title": "Border",
            "heading" : {}
        }]
    }]
}

Displays an image dropwell in the inspector.

{
    "title": "Image",
    "id": "image",
    "image": {}
}

{
    "groups": [{
        "title": "Image Resource Example",
        "properties": [{
            "title": "Image",
            "id": "image",
            "image": {}
        }]
    }]
}

In some cases, it's adventagous to format a value before it's passed to your element's templates. To achieve this, add a format property to the configuration specifying the format string.

Value formatting is support by all controls.

Basic Example

For example, the following creates a slider ranging from 0-12 with a property called padding

{
    "title" : "Padding",
    "id" : "padding",
    "format": "pt-{{value}}",  
    "slider": {
        "default" : 5,
        "min" : 0,
        "max" : 12
    }
}

If the slider is set to 5 and the template contains

{{padding}}

the output will be

pt-5

Arbitrary Value Example

You could also format the control's value to use tailwind's arbitrary value feature. This would allow your element precis control over all css properties. For example, you can control the opacity utility class from tailwind with a slider:

{
    "title" : "Opacity",
    "id" : "opacity",
    "format": "opacity-[{{value}}%]",  
    "slider": {
        "default" : 50,
        "min" : 0,
        "max" : 100
    }
}

If the slider is set to 50 and the template contains

{{opacity}}

the output will be

opacity-[50%]

Advanced CSS Example

You could also format the control's value to output a valid CSS property. For example, if we want to control the translateX css property with a number input, we can do the following:

{
    "title" : "Translate X",
    "id" : "translateX",
    "format": "transform: translateX({{value}}px);",  
    "number": {
        "default" : 50,
    }
}

If the number field is set to 50 and the template contains

{{translateX}}

the output will be

transform: translateX(50px);

Of cause, in this case you would want to add this to a CSS template file.

CSS Custom Property Example

You can even use the format to control a CSS Custom Property (css variable). If we take our previous example and expand on it, we might want to instead set a --translateX CSS custom property with a number input:

{
    "title" : "Translate X",
    "id" : "translateX",
    "format": "--translateX: {{value}}px;",  
    "number": {
        "default" : 50,
    }
}

If the number field is set to 50 and the template contains

{{translateX}}

the output will be

--translateX: 50px;

In this case you would either want to add this to a CSS file, or use an inline style attribute to set the --translateX:

// first you would use the CSS custom property in your CSS:
<style>
.myDiv {
  ...
  transform: scale(0.5) translateX(var(--translateX, 0));
}
</style>

// now that your class is setup to use the --translateX custom property
// you can reassign it locally:
<div class="myDiv" style="{{translateX}}"> ... </div>

// this would output:
<div class="myDiv" style="--translateX: 50px;"> ... </div>

All UI Controls need to be placed inside of a Group. The controls appear in the inspector.

Available Controls

A slider can be used for choosing from a range of values.

The following example displays a stepped slider with seven pre-defined values.

The following example has a minimum value of 0 and maximum of 100. The units are set to round, and display in the UI with a "%" after the number.

An example slider setting a star rating between 0 and 5.

Here's an example of an items array in sliders so you can set custom values for each point in the slider.

Supported Options

The slider control supports the following options.

Displays a resource dropwell that accepts all file types.

Restricting File Types

You can restrict the file types allowed in a dropwell, by using the accepts property.

Support for multiple file types can be added using comma seperated values.

Display some informational static text.

The Link control allows users to input a URL or link to another page within their RapidWeaver project.

Template Example

The following will give you access to the link object in your template file(s).

Getting the Absolute URL

By default the link attribute will return a relative URL. To get the full URL add the absoluteURL property.

Corresponding template example using the absoluteURL.

Display a segmented control.

You can also use the following title key to display text instead of icons.

Displays a number field with a stepper.

Displays the Theme Studio Border Width control.

Displays a text field in the inspector.

Displays a switch, similar to a checkbox in functionality.

The following examples returns a true or false value. Note that responsive should be false.

The following example returns a string value instead of true or false. Note that responsive should be false.

To display this value in a template file, use {{display}}.

Responsive

When using a switch responsively, trueValue and falseValue should be set to a Tailwind class name. You'll then receive a list of Tailwind classes within your template, prefixed for each breakpoint as necessary.

Template

In the Template file you can do the following to display different html based on the value.

Displays a multiline text area in the inspector.

Displays the Theme Studio Color control.

For consistency and integration with the Theme Studio in RapidWeaver Elements, use the themeColor attribute to specify all color options for your elements. This ensures that the color settings are centrally managed and adaptable to theme changes.

Usage of themeColor:

• default: Sets the initial or fallback color and brightness. In this case, the default color is black with a brightness value of 300.

Output Example: controls the output format of the customColor property. In your template files, referencing {{customColor}} with the example configuration above would output: text-black-300.

Setting Light and Dark mode colours

Displays the Theme Studio Border Radius control.

Displays the Theme Studio Text Style control.

{
    "title": "Text Style",
    "id": "headingTextStyles",
    "themeTextStyle": {
        "default": {
            "base": {
                "name": "3xl"
            }
        }
    }
}

{
    "groups": [{
        "title": "Theme Text Style Example",
        "properties": [{
            "title": "Text Style",
            "id": "headingTextStyles",
            "themeTextStyle": {
                "default": {
                    "base": {
                        "name": "3xl"
                    }
                }
            }
        }]
    }]
}

Displays the Theme Studio Shadow control.

{
    "title": "Shadow",
    "id": "boxShadow",
    "themeShadow": {
        "default": {
            "name": "none"
        }
    }
}

{
    "groups": [{
        "title": "Theme Shadow Example",
        "properties": [{
            "title": "Shadow",
            "id": "boxShadow",
            "themeShadow": {
                "default": {
                    "name": "none"
                }
            }
        }]
    }]
}

Displays the Theme Studio Font control.

{
    "title": "Theme Font",
    "id": "fontFamily",
    "themeFont": {
        "default": {
            "base": { "name": "body" },
            "sm": { "name": "heading" },
            "md": { "name": "quote" }
        }
    }
}

{
    "groups": [{
        "title": "Theme Font Example",
        "properties": [{
            "title": "Theme Font",
            "id": "fontFamily",
            "themeFont": {
                "default": {
                    "base": { "name": "body" },
                    "sm": { "name": "heading" },
                    "md": { "name": "quote" }
                }
            }
        }]
    }]
}

For effective theme integration in RapidWeaver Elements, it is recommended to use the themeFont attribute to define all font family settings for your elements. This approach ensures that font preferences are coordinated with the overall theme settings, providing a consistent user experience.

Here’s a structured example for defining a font property:

Output Example: In your template files, referencing {{fontFamily}} with the example configuration above would output: font-sub-heading sm:font-heading md:font-quote.

Template files in RapidWeaver Elements house all the HTML, CSS, JavaScript, and other assets your component needs to work seamlessly. These files are dynamically processed by Elements, allowing for property replacements (think handlebars-style), perform iterations, and more—enabling you to build highly flexible and reusable components.

Templates Directory Structure

The structure of the templates directory is important and denotes in which area the contained files will be inserted into the page. Any files placed at the root of the templates directory will be processed and added for each instance of the component on the page.

The templates directory may also contain the following sub directories

• headStart - placed at the top of head

• headEnd - placed at the end of head

• bodyStart - placed at the top of body

• bodyEnd - placed at the bottom of body

• include - files can be included from other template files using an @include statement

Supported Template File Types

• html - contains HTML content

• js - contains javascript

• css - CSS styles

• php - files containing PHP

Displays the Theme Studio Typography class picker.

 {
          "title": "Typography",
          "id": "typography",
          "themeTypography": {
            "default": {
              "base": {
                "name": "body"
              },
              "md": {
                "name": "heading"
              }
            }
          }
        },

{
    "groups": [{
        "title": "Theme Text Style Example",
        "properties": [
         {
          "title": "Typography",
          "id": "typography",
          "themeTypography": {
            "default": {
              "base": {
                "name": "body"
              },
              "md": {
                "name": "heading"
              }
            }
          }
        },
        ]
    }]
}

Displays the Theme Studio Spacing control.

{
    "title": "Padding",
    "id": "themeSpacing",
    "themeSpacing": {
        "mode": "padding",
        "default": {
            "base": {
                "left": "sm",
                "right": "sm",
                "top": "sm",
                "bottom": "sm"
            },
            "md": {
                "left": "md",
                "right": "md",
                "top": "md",
                "bottom": "md"
            }
        }
    }
}

{
    "groups": [{
        "title": "Theme Spacing Example",
        "properties": [{
            "title": "Padding",
            "id": "themeSpacing",
            "themeSpacing": {
                "mode": "padding",
                "default": {
                    "base": {
                        "left": "sm",
                        "right": "sm",
                        "top": "sm",
                        "bottom": "sm"
                    },
                    "md": {
                        "left": "md",
                        "right": "md",
                        "top": "md",
                        "bottom": "md"
                    }
                }
            }
        }]
    }]
}

The themeSpacing attribute is should be used for all space settings like padding, margins, gaps, translate, and positioning.

This control allows the user's site to dynamically adapt to any theme updates, changes, or overrides to the spacing scale.

The themeSpacing control has the following modes:

• padding

• margin

• gap

• transition

• position

• single

Each one of these modes correspond to the appropriate Tailwind utility classes. This means both developers and users can manage one single spacing scale that help promote consistency across all sites built in RapidWeaver Elements. See the examples below for more information.

{
    "groups": [{
        "title": "Theme Spacing Example",
        "properties": [{
            "title": "Padding",
            "id": "themeSpacing",
            "themeSpacing": {
                "mode": "padding",
                "default": {
                    "base": {
                        "left": "sm",
                        "right": "sm",
                        "top": "sm",
                        "bottom": "sm"
                    },
                    "md": {
                        "left": "md",
                        "right": "md",
                        "top": "md",
                        "bottom": "md"
                    }
                }
            }
        }]
    }]
}

Single Mode

The single mode allows you to access the spacing scale from the Theme Studio in a single select control. This is handy when you need to set a single property rather than all four properties (top, right, bottom left). For example, if you need to set only the top css property you can do so like this:

{
    "title": "Top",
    "id": "top",
    "format": "top-{{value}}"
    "themeSpacing": {
        "mode": "single",
        "default": {
            "base": {
                "value": "2"
            }
        }
    }
}

In this example, the default value will be returned as top-2.

Custom Values

You can also specify that a custom value should be used by default for the themeSpacing control. This allows you to gain precise control over the value of the spacing when your element is dropped on to a page.

Linking Values

If Statement

The following example displays the text inside of the IF statment when the switch is on/true. It's worth noting that only non-responsive controls can be used in 'if' statements.

When performing complex logic like string comparisons, use the to perform this logic and provide simple bool values to the template. This helps to keep templates simple and focused on HTML rather than complex conditional logic.

Else If Statements

Elements allows you to specify a number of else if statements to run before falling back to the else block. An @elseif statement works just like a regular @if statement and follows the same syntax.

Conditional Statement for Edit/Preview Modes

Elements gives you access to the current RapidWeaver mode inside of conditional statements. This can be particularly useful for showing content in edit mode or in preview.

RegEx (Regular Expression) is a powerful tool for searching, matching, and manipulating text based on specific patterns. It uses a combination of characters, meta-characters, and quantifiers to define complex search criteria. RegEx is widely used in programming, text editors, and command-line tools for tasks like input validation, pattern extraction, and string replacement. Its versatility allows users to efficiently find and process text, from simple matches to intricate parsing operations.

In Elements it can be used to conditionally check for values, the following example checks for specific words in a text field before showing a slider.

The portal feature allows you to transport sections of your template code to another part of the page.

If you are linking and including scripts, you'll want to tell Elements to only include the link once (when multiple instances of the same component are on the page). To do that you can use the "includeOne argument.

Include once across multiple components.

An include allows you to insert the content of another template file within the current template file.

Include files should be stored in the directory.

Suppose you have the following template files in your include folder:

hello.html

world.html

You could then include the contents of those files into your main template.html file by using the following code:

The output from template.html would look like this

Property access

The include template files allow access to properties as if they were part of the main template file. Given that you have set a pages value in your hooks file (via the rw.setProps() method), you can pass that property to your template like so:

You can of cause include multiple properties simply by comma separating them:

Conditional Includes

Rather than wrapping your @include statement inside an @if statement, you can use the @includeIf helper:

Setting an anchor in a template file will list it and allow it to be linked to from the Link Panel in the Editor.

<div id="@anchor("myAnchor")"></div>

And using a property:

<div id="@anchor(myAnchorProperty)"></div>

At the start of a template file you can add an inline template that can be included like any other template file. This is handy if you have small parts of your template you want to extract, and don't want or need to create separate templates files.

@template("list-item")
    <li>{{item.name}}</li>
@endtemplate

<h1>My List</h1>
<ul>
    @each(item in items)
        @include("list-item")
    @endeach
</ul>

Dropzone Naming

A dropzones is an area within a template where child element can be added. Each dropzone requires a name giving you a consistent & reliable way to manage child items.

@dropzone("extraItems")

@dropzone(name: "content")

@dropzone("zone-1", title: "Zone 1")

@if(edit)
   @dropzone("extraItems")
@elseif(preview)
   @dropzone("extraItems")
@endif

Resource Dropzone

Sometimes you want to allow the user to drop the resources directly into the Editor, this can be achieved with the rwResourceDropZone key.

The following example shows how to support dropping a folder of images directly into the Editor. Place the following in the Template HTML:

<div class="grid grid-cols-4 gap-4" rwResourceDropZone="images">
    @if(!images.isFolder)
        <!-- if the `images` resource property is not a folder, display this message -->
        <h3 class="font-bold text-lg uppercase text-brand-500 p-10 col-span-full place-self-center">
            Drop a folder of images here!
        </h3>
    @else
        <!-- Otherwise we have a folder of resources (yay!) -->
        @each(image in images.resources)
            <img src="{{image.image}}" alt="{{image.caption}}" />
        @endeach
    @endif
</div>