Layout Properties

Each component has a particular visual appearance by default; this default display is often the best the component can have in a particular context.

However, as you change an application's layout, you may need to change some visual properties of components.

This code snippet renders a text:

<App>
  <Text>I'm a Text without explicit layout properties</Text>
</App>

This sample explicitly sets a few layout properties of Text:

<App>
  <Text
    backgroundColor="cyan"
    width="320px"
    padding="2rem">
    I'm a Text with explicit layout properties
  </Text>
</App>

In this article, you will learn about available layout properties. Before treating them, learn how to use layout properties correctly to avoid unnecessary maintenance chores.

Proper Use of Layout Properties

Layout properties are easy to use; adding simple property values can quickly change the visuals of a particular component.

However, this ease comes at a high price: the more individual layout properties there are, the more tedious the application maintenance is if you need to change the app's appearance.

In this section, you will learn how to use this toolset.

App with Layout Properties

In the following example, all properties of the HStack and CHStack components are layout properties. Some of them set dimensions; others set colors or other style elements:

<App>
  <HStack height="100%">
    <CHStack border="1px dotted blue" color="black" width="80px" height="40px">Black</CHStack>
    <CHStack backgroundColor="red" color="white" width="80px" height="40px">Red</CHStack>
    <CHStack backgroundColor="blue" color="white" width="80px" height="40px">Blue</CHStack>
    <CHStack backgroundColor="purple" color="white" width="80px" height="40px">Purple</CHStack>
    <CHStack backgroundColor="green" color="white" width="80px" height="40px">Green</CHStack>
  </HStack>
</App>

Also, the height property of HStack is a layout property. However, its "100%" value represents a layout constraint (use the full application height for the stack), so it is not likely to change.

If you need to change the dimensions of boxes (80 x 40 pixels is not the right size), you need to modify the width and height properties for all CHStack instances.

App with Reusable Components

Reusable components may help such maintenance nightmares. You can extract the common style traits of individual components into a reusable component.

To remove the pain of setting all width and height occurrences in the previous example (when using layout properties), define a reusable component instead. This new component will be called MyBox with preset dimension values. However, border and color values are allowed to be changed from the outside via properties:

<Component name="MyBox">
  <CHStack
    border="{$props.border}"
    backgroundColor="{$props.bgColor}"
    color="{$props.color}"
    width="80px" height="40px">
    <Slot />
  </CHStack>
</Component>

Now, with the MyBox component, the previous UI declaration is more straightforward:

<App>
  <HStack height="100%">
    <MyBox border="1px dotted blue" color="black">Black</MyBox>
    <MyBox bgColor="red">Red</MyBox>
    <MyBox bgColor="blue">Blue</MyBox>
    <MyBox bgColor="purple">Purple</MyBox>
    <MyBox bgColor="green">Green</MyBox>
  </HStack>
</App>

Let's assume, we need to change the dimensions from 80x40 to 60x60 pixels. Altering the width and height properties within MyBox has its effect on all boxes:

<Component name="MyBox">
  <CHStack
    border="{$props.border}"
    backgroundColor="{$props.bgColor}"
    color="{$props.color ?? 'white'}"
    width="60px" height="60px">
    <Slot />
  </CHStack>
</Component>

App with Theme Variables

XMLUI uses themes. A theme is a set of theme variables with their actual values, which influence an app's appearance. A single app can be shipped with multiple themes; users can select their current theme from the available ones.

You can extract the values of layout properties into theme variables. For example, the hard-wired dimensions of MyBox can be put into theme variables:

<Component name="MyBox">
  <CHStack
    border="{$props.border}"
    backgroundColor="{$props.bgColor}"
    color="{$props.color}"
    width="$width-MyBox"
    height="$height-MyBox">
    <Slot />
  </CHStack>
</Component>

Here, $width-MyBox and $height-MyBox declare two theme variables. When you build and deploy an app, you can set these theme variables in a theme definition. When you change that definition, the app will update the layout properties referencing the altered theme variables.

Changing the dimensions of MyBox is pretty straightforward by setting the appropriate theme variables:

{
  // ... Other theme props omitted
  "themeVars": {
    // ...
    "width-MyBox": "100px",
    "height-MyBox": "30px"
    // ...
  }
}

Dimensions

When the engine renders particular components, it determines their dimensions according to the type of a particular component and its explicitly set dimension properties.

Specifying Dimensions

You can explicitly specify several dimensions of a particular component with the width, height, minWidth, minHeight, maxWidth, and maxHeight layout properties.

The dimension properties use size values, which contain a value and a unit that together determine the actual size. Here are a few examples of size values:

12px
0.25rem
50%
0
125mm

The XMLUI percentage value is relative to the size of the viewport a parent container offers for a particular child element. Here is an example to demonstrate how percentage values are used:

<App>
  <HStack>
    <Stack width="20%" height="36px" backgroundColor="red" />
    <Stack width="40%" height="36px" backgroundColor="green" />
    <Stack width="20%" height="36px" backgroundColor="blue" />
  </HStack>
  <HStack gap="1rem">
    <Stack width="20%" height="36px" backgroundColor="red" />
    <Stack width="33.3%" height="36px" backgroundColor="green" />
    <Stack width="10%" height="36px" backgroundColor="blue" />
  </HStack>
</App>

Component Width and Height

You can change the default component width and height with these layout properties:

The following sample demonstrates the width-related properties.

<App>
  <VStack width="50%" height="36px" backgroundColor="red" />
  <VStack width="30%" minWidth="200px" height="36px" backgroundColor="green" />
  <VStack width="75%" minWidth="200px" maxWidth="300px" height="36px" backgroundColor="blue" />
</App>

Resize the screen to see how the sizes of colored boxes change.

Overflow

A component may not fit into the area its parent provides. This is called overflow. XMLUI provides a few properties to define how a particular component should behave in situations like these. Individual components, such as Text, Heading, and others, provide further techniques to handle overflow.

Horizontal Overflow

The following example demonstrates how the horizontal overflow property works:

<App>
  <VStack width="180px" height="40px" backgroundColor="cyan" overflowX="hidden">
    <Text maxLines="1">
      This is a long text that probably won't fit entirely in a single line.
    </Text>
  </VStack>
  <VStack width="180px" height="40px" backgroundColor="lightgreen" overflowX="scroll">
    <Text color="purple" width="1000px">
      This is a long text that probably won't fit entirely in a single line.
    </Text>
  </VStack>
  <VStack width="180px" height="40px" backgroundColor="silver">
    <Text color="purple">
      This is a long text that probably won't fit entirely in a single line.
    </Text>
  </VStack>
</App>

Observe the second text's width, which is set to 1000px, to ensure it won't be trimmed and closed with ellipses. Due to the overflowX="scroll" setting, you can see a horizontal scrollbar at the bottom of the light green box. The last text has no overflowX value or width constraint, so the engine breaks it into multiple lines. As it has no overflowY value, the engine lets it flow out of its container.

Vertical Overflow

The following example demonstrates how the vertical overflow property works:

<App>
  <VStack width="180px" height="40px" backgroundColor="cyan" overflowY="hidden">
    <Text maxLines="1">
      This is a long text that probably won't fit entirely in a single line.
    </Text>
  </VStack>
  <VStack width="180px" height="40px" backgroundColor="lightgreen" overflowY="scroll">
    <Text color="purple">
      This is a long text that probably won't fit entirely in a single line.
    </Text>
  </VStack>
  <VStack width="180px" height="40px" backgroundColor="silver">
    <Text color="purple">
      This is a long text that probably won't fit entirely in a single line.
    </Text>
  </VStack>
</App>

Each of the three text fragments is enclosed in a box with a fixed size (180 x 40 pixels). Observe the effect of different overflowY values. The last box uses no overflowY, which has the same effect as overflowY="visible".

The Box Model

Most components use a rectangular space (or box) their parent container provides. Several layout properties define how the component should use this rectangular space. These properties follow the so-called box model which comes from the CSS model of the same name.

This model works with the following boxes nested in each other (see an example for each underneath the list):

• Component box: The area the parent provides for the component (the size of this box depends on the rendering logic of the parent).
• Margin box: Within the component box, the component may define a margin that surrounds the other boxes of the component. The margin box displays the background (background color) the parent component provides.
• Border box: Within the margin box, the component may have a border with a particular width. Depending on the border pattern (for example, in the case of a dashed or dotted), the component background may be visible under the border.
• Padding box: The component may define a padding surrounding its content. The background of the padding box is set to the component background.
• Content box: This is the rectangular area where the component will render its child components.

The engine defines several layout properties to set up the box model of a particular component. Here is an example:

<App height="100%" backgroundColor="cyan">
  <VStack height="85%"
    backgroundColor="red"
    margin="20px"
    padding="60px"
    border="8px dashed blue">
    <VStack width="100%" height="100%" backgroundColor="green" />
  </VStack>
</App>

The point of interest in the code snippet is the red rectangle; the markup contains styling to showcase all parts of the box model:

App has a cyan background and encompasses the whole app area because its height is set to 100% and being a block level element, it fills in the available horizontal space as well.

The child with the red background has a margin of 20px and is smaller than its parent (its height is also 85% of its parent). This child also has a dashed border (border="8 dashed blue"), and has a padding of 60px that squishes its own child to occupy less space inside of it (the one with the green background).

Finally, the VStack with the green background fills in the available content area defined by its parent with the red background.

Margin

You can use these properties to define component margins:

When you decorate a component with multiple properties setting the same margin, the most specific one prevails. For example, marginLeft overrides marginHorizontal and margin.

Border

You can use these properties to define component borders:

When you decorate a component with multiple properties setting the same border segment, the most specific one prevails. For example, borderLeft overrides border.

You can also define the rounding of the border through a set of properties:

If you set borderRadius and any other properties, the others overwrite borderRadius for the particular corner.

Padding

You can use these properties to define component paddings:

When you decorate a component with multiple properties setting the same padding, the most specific one prevails. For example, paddingLeft overrides paddingHorizontal and padding.

Component Appearance

Several layout properties determine the visual appearance of a particular component.

Colors

The engine supports these layout properties to set component colors:

Note: Besides these colors, borders and shadows also can declare their display colors.

<App>
  <H2 backgroundColor="green" color="white">The Power of Green Economy</H2>
</App>

<App>
  <H2 backgroundColor="green" color="white" opacity="0.5">
    The Power of Green Economy
  </H2>
</App>

Font and Text Properties

Several properties allow you to set the appearance of text elements displayed in the UI:

<App>
  <Text fontFamily="'Courier New', monospace">
    This should be monospace
  </Text>
  <Text fontWeight="bold">
    This is bold text!
  </Text>
  <Text fontStyle="italic" textDecoration="green wavy underline">
    This is italic with decoration!
  </Text>
</App>

Shadow

You can add shadow effects around a component's frame and set up one or more shadow effects.

<App>
  <VStack width="200px" padding="20px" border="2px solid #202020"
    boxShadow="12px 12px 5px orangered" >
    <Text>This is a box with a shadow around it.</Text>
  </VStack>
</App>

Other Layout Properties

A few layout properties are used for miscellaneous purposes.

Content Alignment

Components that lay out their children according to their strategy (such as Stack, FlowLayout, and others utilize these properties to influence the rendering logic.

Direction

This property sets the direction of text, table columns, and horizontal overflow. Use rtl for languages written from right to left (like Hebrew or Arabic), and ltr for those written from left to right (like English and most other languages). By default, the prop's value is ltr.

<App>
  <Text width="300px" backgroundColor="cyan">
    This goes from left to right
  </Text>
  <Text width="300px" backgroundColor="cyan"
    direction="rtl">
    This goes from right to left
  </Text>
</App>

Gap

Layout components use this property to define the size of space separating child components.

Cursor

This layout property sets the mouse cursor, if any, to show when the mouse pointer is over a particular component.

Orientation

This property specifies a particular component's orientation when displaying its child components.

Z-Index

This layout property sets the z-order of a positioned component and its children. Overlapping components with a larger z-index cover those with a smaller one.