Creating and editing view components

You can create new, reusable view components by turning a container into a composite component.

Simply select a container, and at the bottom of the properties panel, click the Create a composite component button. After a confirmation dialog, the isolation mode is opened for your newly-created component.

In a similar fashion, existing composite components can be edited or used as the basis for a new component by cloning them.

Using the Isolation mode

The Isolation mode essentially lets you edit the structure and properties of a composite component in isolation from the rest of the view. To signify this, the rest of the UI is faded out with a translucent stripe pattern.

For any composite, there's three things to consider:

  • Composite component structure, i.e. how the different containers and child components are laid out.

  • Composite component properties, i.e. what child component properties are exposed on the composite top level.

  • Composite component events, i.e. what child component events are exposed on the composite top level.

Composite component structure

Creating the structure for your composite works the same way in Isolation mode as outside it: you drag components to the canvas and define their properties and styles. Nested containers can be used to do more complex layouting.

The only difference is the root container: outside Isolation mode, the root of your component structure is the view itself, while in Isolation mode, it's the root of the composite component.

Best practices

You can decide yourself if you prefer to build your components first as containers outside Isolation mode, and then turn them into composites later on, or craft a set of composites as a kind of style guide beforehand.

For clarity, try to avoid unnecessary nested containers. For example, there's might not be a need to add a Row component if you can just set a regular Container to have a horizontal layout direction.

Composite component properties

Every component has a set of properties that define how it functions – you can read more in the Component properties panel guide.

The only property inherent to a composite component is Visibility, i.e. is the component shown in the UI or not. All other properties are linked to child component properties.

For example, it makes sense for a card component with a title and a body to expose Title text and Body text properties: when you drag the card onto the view canvas and select it, you can configure both relevant text contents.

Internally, the card composite has two Text primitives, each with a Content property. The composite component's Title text and Body text properties are linked to the respective child component properties.

Thus, setting the Title text on the composite actually sets the Content property of the title Text primitive inside it.

Best practices

When you are building a composite component, try to prioritize ease-of-use and clarity over configurability.

It doesn't make sense to make every child component's Visibility property available as a composite property, unless your composite specifically requires that. Rather, strive for the least number of properties, and if things start to get complex, consider just making a separate component.

Note on styles

Currently, you cannot define what child component styles are exposed to the composite top level. Instead, you should use theme variables to provide that configurability. This means that instead of black, your component header should be bound to $h1Color and so on. This will make your component compatible with the various themes available on the Marketplace.

Composite component events

Component primitives expose various kinds of native events: Component tapped, Input value changed, Input field focused and so on. In some cases, you want to expose these events from your child components onto the composite's top level logic canvas, so they can be utilized by whoever's using your component.

For example, a list item might have both a generic tap event on the whole component, as well as a specific tap event on the info icon.

To make a child component event available on the composite main canvas, you drag an Event in node to the composite's top level logic canvas. It should have Fired from an Event out node as its event source and a descriptive name, such as "Info icon tapped".

Then, go to the logic canvas of the child component, drag in an Event out node and connect it to the desired child component event – in our example, the info icon and its tap event. Then, configure the Event out node to trigger the Event in node on the top level canvas, e.g. "Info icon tapped".

Now, the event fired by the native side when the info icon is tapped immediately triggers the "Info icon tapped" event and whatever logic the person using your composite component has attached to it.