> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stac.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Positioned

> Documentation for Positioned

export const PLAYGROUND_BASE_URL = "https://playground.stac.dev/";

export const positionedPreviewJson = {
  "type": "stack",
  "children": [{
    "type": "positioned",
    "left": 10,
    "top": 20,
    "right": 30,
    "bottom": 40,
    "child": {
      "type": "text",
      "data": "Hello, World!"
    }
  }]
};
export const positionedPreviewSrc = `${PLAYGROUND_BASE_URL}/embed`;

The Stac Positioned widget controls where a child of a [Stack](https://api.flutter.dev/flutter/widgets/Stack-class.html) is positioned. It corresponds to Flutter's Positioned widget and allows precise positioning using coordinates and optional sizing constraints. Use it with JSON to declare positioned children inside a Stack.

To learn more about the Positioned widget in Flutter, see the [official documentation](https://api.flutter.dev/flutter/widgets/Positioned-class.html).

## Positioning constraints

Only **two of the three** horizontal values (`left`, `right`, `width`) may be set; at least one must be omitted or null. Similarly, only **two of the three** vertical values (`top`, `bottom`, `height`) may be set; at least one must be omitted or null.

## Properties

| Property | Type         | Description                                     |
| -------- | ------------ | ----------------------------------------------- |
| left     | `double?`    | The distance from the left edge of the stack.   |
| top      | `double?`    | The distance from the top edge of the stack.    |
| right    | `double?`    | The distance from the right edge of the stack.  |
| bottom   | `double?`    | The distance from the bottom edge of the stack. |
| width    | `double?`    | The width of the positioned child.              |
| height   | `double?`    | The height of the positioned child.             |
| child    | `StacWidget` | The widget to position within the stack.        |

<Note>
  The Dart API also supports named constructors: `StacPositioned.fill()`, `StacPositioned.fromRect()`, `StacPositioned.fromRelativeRect()`, and `StacPositioned.directional()`. These are not available in JSON format.
</Note>

## Example

<Tabs sync={false}>
  <Tab title="Dart">
    ```dart theme={null}
    StacPositioned(
      left: 10,
      top: 20,
      right: 30,
      bottom: 40,
      child: StacText(data: 'Hello, World!'),
    )
    ```
  </Tab>

  <Tab title="JSON">
    ```json theme={null}
    {
      "type": "stack",
      "children": [
        {
          "type": "positioned",
          "left": 10,
          "top": 20,
          "right": 30,
          "bottom": 40,
          "child": {
            "type": "text",
            "data": "Hello, World!"
          }
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Preview">
    <Frame>
      <iframe
        id="stac"
        src={positionedPreviewSrc}
        title="Stac Playground"
        className="w-full rounded-xl border-0"
        style={{ height: "640px" }}
        loading="lazy"
        onLoad={(event) => {
      const iframe = event.currentTarget;
      const targetOrigin = PLAYGROUND_BASE_URL;
      const message = {
        type: "stac-preview-json",
        payload: positionedPreviewJson
      };

      let attempts = 0;
      const maxAttempts = 12;
      const interval = setInterval(() => {
        iframe.contentWindow?.postMessage(message, targetOrigin);
        attempts += 1;

        if (attempts >= maxAttempts) {
          clearInterval(interval);
        }
      }, 250);
    }}
      />
    </Frame>
  </Tab>
</Tabs>

## Dart-Only Constructors

The following named constructors are available in Dart but not in JSON:

### `StacPositioned.fill()`

Creates a positioned widget with `left`, `top`, `right`, and `bottom` defaulting to `0.0`, so the child fills the stack unless overridden.

```dart theme={null}
StacPositioned.fill(
  left: 10,
  top: 20,
  right: 30,
  bottom: 40,
  child: StacText(data: 'Fills the stack'),
)
```

### `StacPositioned.fromRect()`

Creates a positioned widget from a `StacRect`, setting `left`, `top`, `width`, and `height`. `right` and `bottom` are set to null.

```dart theme={null}
StacPositioned.fromRect(
  rect: StacRect(left: 10, top: 20, width: 100, height: 50),
  child: StacText(data: 'From rect'),
)
```

### `StacPositioned.fromRelativeRect()`

Creates a positioned widget from relative edges: `left`, `top`, `right`, and `bottom` are required; `width` and `height` are null.

```dart theme={null}
StacPositioned.fromRelativeRect(
  left: 10,
  top: 20,
  right: 30,
  bottom: 40,
  child: StacText(data: 'Relative rect'),
)
```

### `StacPositioned.directional()`

Creates a positioned widget using `start` and `end` instead of `left` and `right`. The mapping depends on `textDirection`: for LTR, `start` → `left` and `end` → `right`; for RTL, the opposite. Only two of `start`, `end`, and `width` may be set; only two of `top`, `bottom`, and `height` may be set.

```dart theme={null}
StacPositioned.directional(
  textDirection: StacTextDirection.ltr,
  start: 10,
  top: 20,
  width: 100,
  height: 50,
  child: StacText(data: 'Directional positioning'),
)
```