> ## 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.

# Hero

> Documentation for Hero

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

export const heroPreviewJson = {
  "type": "hero",
  "tag": "userAvatar",
  "child": {
    "type": "image",
    "network": "https://example.com/avatar.png"
  }
};
export const heroPreviewSrc = `${PLAYGROUND_BASE_URL}/embed`;

The Stac Hero allows you to build a Flutter Hero widget using JSON. It enables hero animations between routes by tagging widgets with the same tag.
To know more about the Hero widget in Flutter, refer to the [official documentation](https://api.flutter.dev/flutter/widgets/Hero-class.html).

## Properties

| Property                 | Type         | Description                                                              |
| ------------------------ | ------------ | ------------------------------------------------------------------------ |
| tag                      | `String`     | **Required.** The hero tag used to match heroes across routes.           |
| child                    | `StacWidget` | **Required.** The widget subtree for this hero.                          |
| createRectTween          | `StacWidget` | Optional rectangle tween configuration for the hero animation.           |
| flightShuttleBuilder     | `StacWidget` | Optional widget used as the in-flight shuttle during the hero animation. |
| placeholderBuilder       | `StacWidget` | Optional placeholder widget displayed while the destination hero builds. |
| transitionOnUserGestures | `bool`       | Whether the hero should participate in a user gesture driven transition. |

## Example

<Tabs sync={false}>
  <Tab title="Dart">
    ```dart theme={null}
    StacHero(
      tag: 'userAvatar',
      child: StacImage(network: 'https://example.com/avatar.png'),
    )
    ```
  </Tab>

  <Tab title="JSON">
    ```json theme={null}
    {
      "type": "hero",
      "tag": "userAvatar",
      "child": {
        "type": "image",
        "network": "https://example.com/avatar.png"
      }
    }
    ```
  </Tab>

  <Tab title="Preview">
    <Frame>
      <iframe
        id="stac"
        src={heroPreviewSrc}
        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: heroPreviewJson
      };

      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>

## Hero Animation Example

Here's an example showing a hero animation from a list to a detail page:

<CodeGroup>
  ```dart Dart theme={null}
  // List Item
  StacGestureDetector(
    onTap: StacNavigateAction(
      routeName: '/detail',
    ),
    child: StacHero(
      tag: 'product-1',
      child: StacImage(
        network: 'https://example.com/product.png',
        width: 100.0,
        height: 100.0,
      ),
    ),
  )

  // Detail Page
  StacHero(
    tag: 'product-1',
    child: StacImage(
      network: 'https://example.com/product.png',
      width: 300.0,
      height: 300.0,
    ),
  )
  ```

  ```json JSON theme={null}
  // List Item
  {
    "type": "gestureDetector",
    "onTap": {
      "actionType": "navigate",
      "routeName": "/detail"
    },
    "child": {
      "type": "hero",
      "tag": "product-1",
      "child": {
        "type": "image",
        "network": "https://example.com/product.png",
        "width": 100.0,
        "height": 100.0
      }
    }
  }

  // Detail Page
  {
    "type": "hero",
    "tag": "product-1",
    "child": {
      "type": "image",
      "network": "https://example.com/product.png",
      "width": 300.0,
      "height": 300.0
    }
  }
  ```
</CodeGroup>