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

# Badge

> Documentation for Badge

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

export const badgePreviewJson = {
  "type": "badge",
  "label": {
    "type": "text",
    "data": "5"
  },
  "child": {
    "type": "icon",
    "icon": "notifications",
    "size": 32
  },
  "backgroundColor": "#F44336",
  "textColor": "#FFFFFF"
};
export const badgePreviewSrc = `${PLAYGROUND_BASE_URL}/embed`;

The Stac Badge allows you to build a Flutter Badge widget using JSON.
To know more about the Badge widget in Flutter, refer to the [official documentation](https://api.flutter.dev/flutter/material/Badge-class.html).

## Properties

| Property        | Type                    | Description                                                                                                                                            |
| --------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| backgroundColor | `StacColor`             | The badge's fill color (hex string). Defaults to `ColorScheme.error` from theme.                                                                       |
| textColor       | `StacColor`             | The color of the badge's label text (hex string). Defaults to `ColorScheme.onError` from theme.                                                        |
| smallSize       | `double`                | The diameter of the badge if \[label] is null. Defaults to 6.0.                                                                                        |
| largeSize       | `double`                | The badge's height if \[label] is non-null. Defaults to 16.0.                                                                                          |
| textStyle       | `StacTextStyle`         | The text style for the badge's label.                                                                                                                  |
| padding         | `StacEdgeInsets`        | The padding added to the badge's label. Defaults to 4 pixels horizontal.                                                                               |
| alignment       | `StacAlignmentGeometry` | Combined with \[offset] to determine the location of the \[label]. Defaults to `AlignmentDirectional.topEnd`.                                          |
| offset          | `StacOffset`            | Combined with \[alignment] to determine the location of the \[label].                                                                                  |
| label           | `StacWidget`            | The badge's content, typically a \[StacText] widget. If null, displays as a small filled circle.                                                       |
| count           | `int`                   | Convenience property for creating a badge with a numeric label. Automatically creates label showing count or '\[maxCount]+' if count exceeds maxCount. |
| maxCount        | `int`                   | Maximum count value before showing '\[maxCount]+' format. Only used when \[count] is provided. Defaults to 999.                                        |
| isLabelVisible  | `bool`                  | If false, the badge's \[label] is not included. Defaults to `true`.                                                                                    |
| child           | `StacWidget`            | The widget that the badge is stacked on top of. Typically an Icon or IconButton.                                                                       |

## Example

### Basic Badge with Label

<Tabs sync={false}>
  <Tab title="Dart">
    ```dart theme={null}
    StacBadge(
      label: StacText(data: '5'),
      child: StacIcon(icon: 'notifications', size: 32),
      backgroundColor: '#F44336',
      textColor: StacColors.white,
    )
    ```
  </Tab>

  <Tab title="JSON">
    ```json theme={null}
    {
      "type": "badge",
      "label": {
        "type": "text",
        "data": "5"
      },
      "child": {
        "type": "icon",
        "icon": "notifications",
        "size": 32
      },
      "backgroundColor": "#F44336",
      "textColor": "#FFFFFF"
    }
    ```
  </Tab>

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

      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>

### Badge with Count

<CodeGroup>
  ```dart Dart theme={null}
  StacBadge(
    count: 5,
    child: StacIcon(icon: 'shopping_cart', size: 32),
  )
  ```

  ```json JSON theme={null}
  {
    "type": "badge",
    "count": 5,
    "child": {
      "type": "icon",
      "icon": "shopping_cart",
      "size": 32
    }
  }
  ```
</CodeGroup>

### Badge with Count Exceeding MaxCount

<CodeGroup>
  ```dart Dart theme={null}
  StacBadge(
    count: 1000,
    maxCount: 99,
    child: StacIcon(icon: 'notifications', size: 32),
  )
  ```

  ```json JSON theme={null}
  {
    "type": "badge",
    "count": 1000,
    "maxCount": 99,
    "child": {
      "type": "icon",
      "icon": "notifications",
      "size": 32
    }
  }
  ```
</CodeGroup>

### Small Badge (No Label)

<CodeGroup>
  ```dart Dart theme={null}
  StacBadge(
    smallSize: 8,
    backgroundColor: '#F44336',
    child: StacIcon(icon: 'circle', size: 32),
  )
  ```

  ```json JSON theme={null}
  {
    "type": "badge",
    "smallSize": 8,
    "backgroundColor": "#F44336",
    "child": {
      "type": "icon",
      "icon": "circle",
      "size": 32
    }
  }
  ```
</CodeGroup>

### Badge on IconButton

<CodeGroup>
  ```dart Dart theme={null}
  StacBadge(
    count: 3,
    child: StacIconButton(
      icon: StacIcon(icon: 'notifications', size: 24),
      padding: StacEdgeInsets.all(0),
      onPressed: StacNoneAction(),
    ),
  )
  ```

  ```json JSON theme={null}
  {
    "type": "badge",
    "count": 3,
    "child": {
      "type": "iconButton",
      "icon": {
        "type": "icon",
        "icon": "notifications",
        "size": 24
      },
      "padding": {
        "left": 0,
        "top": 0,
        "right": 0,
        "bottom": 0
      },
      "onPressed": {
        "actionType": "none"
      }
    }
  }
  ```
</CodeGroup>

### Badge with Custom Styling

<CodeGroup>
  ```dart Dart theme={null}
  StacBadge(
    label: StacText(data: 'NEW'),
    backgroundColor: StacColors.green,
    textColor: StacColors.white,
    largeSize: 20,
    padding: StacEdgeInsets(left: 8, top: 4, right: 8, bottom: 4),
    alignment: StacAlignment(dx: 1.0, dy: -1.0),
    offset: StacOffset(dx: 4, dy: -4),
    child: StacIcon(icon: 'mail', size: 32),
  )
  ```

  ```json JSON theme={null}
  {
    "type": "badge",
    "label": {
      "type": "text",
      "data": "NEW"
    },
    "backgroundColor": "#4CAF50",
    "textColor": "#FFFFFF",
    "largeSize": 20,
    "padding": {
      "left": 8,
      "top": 4,
      "right": 8,
      "bottom": 4
    },
    "alignment": {
      "dx": 1.0,
      "dy": -1.0
    },
    "offset": {
      "dx": 4,
      "dy": -4
    },
    "child": {
      "type": "icon",
      "icon": "mail",
      "size": 32
    }
  }
  ```
</CodeGroup>