---
title: Properties
description: Properties
---

import Link from '@slint/common-files/src/components/Link.astro';

All elements have properties. Built-in elements come with common properties such
as color or dimensional properties.

## Assigning bindings

You can assign values or entire <Link type="Expressions" /> to them:

```slint
export component Example inherits Window {
    // Simple expression: ends with a semi colon
    width: 42px;
    // or a code block (no semicolon needed)
    height: { 42px }
}
```

Properties in Slint can be assigned using either a simple **expression**, which ends with a semicolon (`;`),
or a **code block**, enclosed in `{ ... }`, which does not require a semicolon.
These two forms are interchangeable for simple values, but a block is useful when you need multiple statements.

For example, these two bindings are equivalent:

```slint no-test
background: touch-area.is-pressed ? red : blue;

background: {
    if (touch-area.is-pressed) {
        return red;
    } else {
        return blue;
    }
}
```

Both forms are reactive, and Slint will automatically track dependencies used within the expression or block.

The default value of a property is the default value of the type.
For example a boolean property defaults to `false`, an `int` property to zero, etc.

## Declaring Properties

In addition to the existing properties, define extra properties by specifying the
type, the name, and optionally a default value:

```slint
export component Example {
    // declare a property of type int with the name `my-property`
    property<int> my-property;

    // declare a property with a default value
    property<int> my-second-property: 42;
}
```

Annotate extra properties with a qualifier that specifies how the
property can be read and written:

-   **`private`** (the default): The property can only be accessed from within the component.
-   **`in`**: The property is an input. It can be set and modified by the user of this component,
    for example through bindings or by assignment in callbacks.
    The component can provide a default binding, but it can't overwrite it by
    assignment
-   **`out`**: An output property that can only be set by the component. It's read-only for the
    users of the components.
-   **`in-out`**: The property can be read and modified by everyone.

```slint
export component Button {
    // This is meant to be set by the user of the component.
    in property <string> text;
    // This property is meant to be read by the user of the component.
    out property <bool> pressed;
    // This property is meant to both be changed by the user and the component itself.
    in-out property <bool> checked;

    // This property is internal to this component.
    private property <bool> has-mouse;
}
```

All properties declared at the top level of a component that aren't `private` are accessible from the outside when using a component as an element, or via the
language bindings from the business logic.

## Change Callbacks

In Slint, it's possible to define a callback that is invoked when a property's value changes.

```slint
import { LineEdit } from "std-widgets.slint";
export component Example inherits Window  {
    VerticalLayout {
        LineEdit {
            // This callback is invoked when the `text` property of the LineEdit changes
            changed text => { t.text = self.text; }
        }
        t := Text {}
    }
}
```

Note that these callbacks aren't invoked immediately.
Instead, they're queued for invocation in the subsequent iteration of the event loop.
A callback is invoked only if the property's value has indeed changed.
If a property's value changes multiple times within the same event loop cycle, the callback is invoked only once.
Additionally, if a property's value changes and then reverts to its original state before the callback is executed, the callback won't be invoked.

**Warning:** Altering properties during a change event in a way that could lead to the same property being affected is undefined behavior.

```slint
export component Example {
    in-out property <int> foo;
    property <int> bar: foo + 1;
    // This setup creates a potential loop between `foo` and `bar`, and the outcome is undefined.
    changed bar => { foo += 1; }
}
```

The above represents an infinite loop. Slint will break the loop after a few iterations.
Consequently, if there's a sequence of changed callbacks where one callback triggers another change callback,
this sequence might break, and further callbacks won't be invoked.

Therefore, it's crucial not to overuse changed callbacks.

**Warning:** Utilize changed callbacks only when an alternative through binding isn't feasible.

For instance, avoid doing this:

```slint no-test
changed bar => { foo = bar + 1; }
```

Instead, opt for:

```slint no-test
foo: bar + 1;
```

Declarative bindings automatically manage dependencies.
Using a changed callback forces immediate evaluation of bindings, which are typically evaluated lazily.
This practice also compromises the purity of bindings, complicating edits via graphical editors.
Accumulating excessive changed events can introduce issues and bugs, especially in scenarios involving loops, where a change callback modifies a property, potentially triggering changes to the same property.

