---
title: "Common Properties & Callbacks"
description: "Common Properties & Callbacks"
---
import SlintProperty from '@slint/common-files/src/components/SlintProperty.astro';
import CodeSnippetMD from '@slint/common-files/src/components/CodeSnippetMD.astro';
import Link from '@slint/common-files/src/components/Link.astro';

The Slint elements have many common properties, callbacks and behavior.
This page describes these properties and their usage.


## Common Visual Properties

These properties are valid on all visual items. For example `Rectangle`, `Text`, and `layouts`. Non
visual items such as `Timer` don't have these properties.


### x, y
<SlintProperty propName="x, y" typeName="length" >
The position of the element relative to its parent.
</SlintProperty>

### z
<SlintProperty propName="z" typeName="float" >
The stacking order of the element among its siblings.
A sibling with a higher `z` is drawn on top, and is the first to receive input.
The default is 0, and siblings that share the same `z` keep their declaration order.
</SlintProperty>


### width, height
<SlintProperty propName="width, height" typeName="length" >
The width and height of the element. When set, this overrides the default size.
</SlintProperty>


### Transforms

Transforms allow for rotating and scaling items around a specified origin point. The default origin point is the center of the element.

Transforms are not available for the software renderer.

```slint {5-7}
Image {
    x: 0;
    y: 0;
    source: @image-url("images/slint-logo.svg");
    transform-rotation: 45deg;
    transform-origin: {x: 0, y: 0};
}
```

#### transform-rotation
<SlintProperty propName="transform-rotation" typeName="angle" defaultValue='0deg'/>

#### transform-origin
<SlintProperty propName="transform-origin" typeName="struct" structName="Point" defaultValue='{x: self.width / 2, y: self.height / 2}'>
The origin to rotate and scale around.

Default to the center of the element.
</SlintProperty>

#### transform-scale
<SlintProperty propName="transform-scale" typeName="float" defaultValue='100%'>
The scale factor to apply to the element and all its children.

This doesn't affect the geometry (width, height) of the element, but affects the rendering.
The scale is done around the `transform-origin` point.

It is also possible to use the `transform-scale-x` and `transform-scale-y` properties to specify the scale factors for the x and y axis.
</SlintProperty>

#### transform-scale-x
<SlintProperty propName="transform-scale-x" typeName="float" defaultValue='self.scale'/>
#### transform-scale-y
<SlintProperty propName="transform-scale-y" typeName="float" defaultValue='self.scale'/>

### opacity
<CodeSnippetMD imagePath="/src/assets/generated/rectangle-opacity.png" scale="3" imageWidth="100" imageHeight="310"  imageAlt='rectangle opacity'>
```slint playground
component ImageInfo inherits Rectangle {
    in property <float> img-opacity: 1.0;
    background: transparent;
    VerticalLayout {
        spacing: 5px;
        Image {
            source: @image-url("elements/slint-logo.png");
            opacity: img-opacity;
        }
        Text {
            text: "opacity: " + img-opacity;
            color: white;
            horizontal-alignment: center;
        }
    }
}
export component Example inherits Window {
    width: 100px;
    height: 310px;
    background: transparent;
    Rectangle {
        background: #141414df;
        border-radius: 10px;
    }
    VerticalLayout {
        spacing: 15px;
        padding-top: 10px;
        padding-bottom: 10px;
        ImageInfo {
            img-opacity: 1.0;
        }
        ImageInfo {
            img-opacity: 0.6;
        }
        ImageInfo {
            img-opacity: 0.3;
        }
    }
}
```
</CodeSnippetMD>

<SlintProperty propName="opacity" typeName="float" defaultValue="1">
A value between `0` and `1` (or a percentage) that is used to draw
the element and its children with transparency.

- `0`: fully transparent (invisible)
- `1`: fully opaque

The opacity is applied to the tree of child elements as if they
were first drawn onto an intermediate layer, and then the whole layer is rendered with this opacity.

The following example demonstrates the opacity property with children.

:::note
The software renderer does not support layer opacity and this results in a different end result as shown.
:::

<CodeSnippetMD imagePath="/src/assets/generated/layer-opacity.png" scale="3" imageWidth="150" imageHeight="390"  imageAlt='layer opacity'>
```slint playground
# export component CheckerBoardRow inherits HorizontalLayout {
#     property <length> size: 15px;
#     property <int> columns: root.width / size;
#     in property <bool> isOdd: true;
#     property <int> isModOdd: isOdd ? 1 : 0;
#
#     height: size;
#     width: 200px;
#     for i in columns : Rectangle {
#         width: size;
#         height: size;
#         background: i.mod(2) == isModOdd ? #262626 : #2c2c2e;
#     }
# }
#
# export component CheckerBoard inherits VerticalLayout {
#     in property <length> size: 15px;
#     property <int> rows: root.height / size;
#
#     width: 200px;
#     height: 400px;
#     for i in rows : CheckerBoardRow {
#         isOdd: i.mod(2) != 0;
#     }
# }
# export component ExportedComponent2 inherits Window {
#     width: 150px;
#     height: 410px;
#     background: transparent;
#     CheckerBoard {
#         width: parent.width;
#         height: parent.height;
#     }
#     VerticalLayout {
#         spacing: 15px;
#         padding-top: 10px;
#         padding-bottom: 10px;
#         VerticalLayout {
#             spacing: 5px;
Rectangle {
    width: 100px;
    height: 150px;
    opacity: 50%;
    Rectangle {
        x: 0;
        y: 0;
        width: 100px;
        height: 100px;
        background: blue;
    }

    Rectangle {
        x: 50px;
        y: 50px;
        width: 100px;
        height: 100px;
        background: green;
    }
}
#             Text {
#                 text: "With Layer Opacity";
#                 color: white;
#                 horizontal-alignment: center;
#             }
#         }
#         VerticalLayout {
#             spacing: 5px;
#             Rectangle {
#                 width: 100px;
#                 height: 150px;
#                 Rectangle {
#                     x: 0;
#                     y: 0;
#                     width: 100px;
#                     height: 100px;
#                     background: blue;
#                     opacity: 50%;
#                 }
#                 Rectangle {
#                     x: 50px;
#                     y: 50px;
#                     width: 100px;
#                     height: 100px;
#                     background: green;
#                     opacity: 50%;
#                 }
#             }
#             Text {
#                 text: "Without Layer Opacity\n(Software Renderer Only)";
#                 color: white;
#                 horizontal-alignment: center;
#             }
#         }
#     }
# }
```
</CodeSnippetMD>

</SlintProperty>

### visible
<SlintProperty propName="visible" typeName="bool" defaultValue="true">
When set to `false`, the element and all its children won't be drawn and won't react to mouse input. The element
still takes up layout space within any layout container.

</SlintProperty>

### absolute-position
<SlintProperty propName="absolute-position" typeName="struct" structName="Point" propertyVisibility="out">

In a UI with many nested components it's useful to know their (x,y)position relative to the main window or screen.
This convenience property gives easy read only access to that value. It represents a point specifying the absolute position within the enclosing [Window](/master/docs/slint/reference/window/window.md) or [PopupWindow](/master/docs/slint/reference/window/popupwindow.md).
It defines coordinates (x,y) relative to the enclosing Window or PopupWindow, but the reference frame is unspecified
(could be screen, window, or popup coordinates).
</SlintProperty>



## Miscellaneous

### cache-rendering-hint
<SlintProperty typeName="bool" propName="cache-rendering-hint" defaultValue="false" >
When set to `true`, this provides a hint to the renderer to cache the contents of the element
and all the children into an intermediate cached layer. For complex sub-trees that rarely
change this may speed up the rendering, at the expense of increased memory consumption.

:::note
Not all rendering backends support this property.
:::
</SlintProperty>



### dialog-button-role
<SlintProperty typeName="enum" enumName="DialogButtonRole" defaultValue="none">
Specify that this is a button in a `Dialog`.
</SlintProperty>

## Common Callbacks

### init()

Every element implicitly declares an `init` callback. You can assign a code block to the element to invoke when
it's instantiated and after all properties are initialized with the value of their final binding. The order of
invocation is from inside to outside. The following example prints "first", then "second", and then "third":

```slint
component MyButton inherits Rectangle {
    in-out property <string> text: "Initial";
    init => {
        // If `text` is queried here, it will have the value "Hello".
        debug("first");
    }
}

component MyCheckBox inherits Rectangle {
    init => { debug("second"); }
}

export component MyWindow inherits Window {
    MyButton {
        text: "Hello";
        init => { debug("third"); }
    }
    MyCheckBox {
    }
}
```

Don't use this callback to initialize properties, because this violates the declarative principle.

Even though the `init` callback exists on all components, it cannot be set from application code,
for example, an `on_init` function does not exist in the generated code.
This is because the callback is invoked when the component is created,
before you could call `on_init` to actually set it.

While the `init` callback can invoke other callbacks, such as one defined in a `global` section, and
you _can_ bind these in the backend, this doesn't work for statically-created components, including
the window itself, because you need an instance to set the globals binding. But it is possible
to use this for dynamically created components (for example ones behind an `if`):

```slint
export global SystemService  {
    // This callback can be implemented in native code using the Slint API
    callback ensure_service_running();
}

component MySystemButton inherits Rectangle {
    init => {
        SystemService.ensure_service_running();
    }
    // ...
}

export component AppWindow inherits Window {
    in property <bool> show-button: false;

    // MySystemButton isn't initialized at first, only when show-button is set to true.
    // At that point, its init callback will call ensure_service_running()
    if show-button : MySystemButton {}
}
```

## Accessibility Properties

Use the following `accessible-` properties to make your items interact well with software like screen readers, braille terminals and other software to make your application accessible.
`accessible-role` must be set in order to be able to set any other accessible property or callback.

### accessible-role
<SlintProperty typeName="enum" enumName="AccessibleRole">
The role of the element. This property is mandatory to be able to use any other accessible properties. It should be set to a constant value. (default value: `none` for most elements, but `text` for the Text element)
</SlintProperty>

### accessible-checkable
<SlintProperty typeName="bool" propName="accessible-checkable" defaultValue="false">
Whether the element is can be checked or not.
</SlintProperty>

### accessible-checked
<SlintProperty typeName="bool" propName="accessible-checked" defaultValue="false">
Whether the element is checked or not. This maps to the "checked" state of checkboxes, radio buttons, and other widgets.
</SlintProperty>

### accessible-description
<SlintProperty typeName="string" propName="accessible-description" defaultValue='""'>
The description for the current element.
</SlintProperty>

### accessible-enabled
<SlintProperty typeName="bool" propName="accessible-enabled" defaultValue="true">
Whether the element is enabled or not. This maps to the "enabled" state of most widgets. (default value: `true`)
</SlintProperty>

### accessible-expandable
<SlintProperty typeName="bool" propName="accessible-expandable" defaultValue="false">
Whether the element can be expanded or not. For example, a `ComboBox` widget should set this to true,
as its selection can be changed via an expandable popup.
</SlintProperty>

### accessible-expanded
<SlintProperty typeName="bool" propName="accessible-expanded" defaultValue="false">
Whether the element is expanded or not. Applies to combo boxes, menu items,
tree view items and other widgets.
</SlintProperty>

### accessible-id
<SlintProperty typeName="string" propName="accessible-id" defaultValue='""'>
A unique identifier for the element, used to identify widgets for automation and testing purposes.
This property can be set to any string value and is particularly useful when writing automated tests or
when using accessibility tools to uniquely identify specific widgets in your application.

If you need to identify repeated elements, make sure to assign different values to each instance as illustrated below.

```slint
for i in 5: Rectangle {
    accessible-role: button;
    accessible-id: "btn-" + i;
    accessible-label: "Button " + i;
}
```
</SlintProperty>

### accessible-label
<SlintProperty typeName="string" propName="accessible-label" defaultValue='""'>
The label for an interactive element. (default value: empty for most elements, or the value of the `text` property for Text elements)
</SlintProperty>

### accessible-orientation
<SlintProperty typeName="enum" enumName="Orientation">
The orientation of the element when it makes sense, such as a `Slider` or a `ScrollBar`. Assistive
technologies can use this to inform the user whether the widget is laid out horizontally or vertically.
</SlintProperty>

### accessible-live-region
<SlintProperty typeName="enum" propName="accessible-live-region" enumName="AccessibleLiveness">
Marks the element as a live region whose textual content should be announced by assistive
technologies when it changes. Use `polite` for non-urgent updates and `assertive` for updates that
should interrupt the user. The default `off` disables live announcements.
</SlintProperty>

### accessible-value-maximum
<SlintProperty typeName="float" propName="accessible-value-maximum" defaultValue="0">
The maximum value of the item. This is used for example by spin boxes.
</SlintProperty>

### accessible-value-minimum
<SlintProperty typeName="float" propName="accessible-value-minimum" defaultValue="0">
The minimum value of the item.
</SlintProperty>

### accessible-value-step
<SlintProperty typeName="float" propName="accessible-value-step" defaultValue="0">
The smallest increment or decrement by which the current value can change. This corresponds to the step by which a handle on a slider can be dragged.
</SlintProperty>

### accessible-value
<SlintProperty typeName="string" propName="accessible-value" defaultValue='""'>
The current value of the item.
</SlintProperty>

### accessible-placeholder-text
<SlintProperty typeName="string" propName="accessible-placeholder-text" defaultValue='""'>
A placeholder text to use when the item's value is empty. Applies to text elements.
</SlintProperty>

### accessible-read-only
<SlintProperty typeName="bool" propName="accessible-read-only" defaultValue="false">
Whether the element's content can be edited. This maps to the "read-only" state of line edit and text edit widgets.
</SlintProperty>

### accessible-item-selectable
<SlintProperty typeName="bool" propName="accessible-item-selectable" >
Whether the element can be selected or not.
</SlintProperty>

### accessible-item-selected
<SlintProperty typeName="bool" propName="accessible-item-selected" >
Whether the element is selected or not. This maps to the "is-selected" state of listview items.
</SlintProperty>

### accessible-item-index
<SlintProperty typeName="int" propName="accessible-item-index">
 The index (starting from 0) of this element in a group of similar elements. Applies to list items, radio buttons and other elements.
</SlintProperty>

### accessible-item-count
<SlintProperty typeName="int" propName="accessible-item-count">
The total number of elements in a group. Applies to the parent container of a group of element such as list views, radio button groups or other grouping elements.
</SlintProperty>


## Accessibility Callbacks
You can also use the following callbacks that are invoked by the accessibility framework:

### accessible-action-default()
Invoked when the default action for this widget is requested, for example pressed for a button.

### accessible-action-set-value(string)
Invoked when the user wants to change the accessible value.

### accessible-action-increment()
Invoked when the user requests to increment the value.

### accessible-action-decrement()
Invoked when the user requests to decrement the value.

### accessible-action-expand()
Invoked when the user requests to expand the widget, such as disclose the list of available choices for a combo box.

### accessible-action-set-selection-offsets(anchor: int, focus: int)
Invoked when the user wants to change the selected text. The arguments are UTF-8 offsets into the element's text: `anchor` is the end that stays put and `focus` the end being moved, so `focus` may precede `anchor` when the selection was made backwards, and the two are equal when only the cursor moved.