Skip to content

feat: Introduce stacBadge widget and parser with example JSON #388

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: dev
Choose a base branch
from
Open

feat: Introduce stacBadge widget and parser with example JSON #388

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9a3da7b
feat: Introduce StacBadge widget and parser with example JSON
kumar-gautam24 Nov 29, 2025
077c0ce
feat: Add documentation for StacBadge widget and example JSON configu…
kumar-gautam24 Dec 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
150 changes: 150 additions & 0 deletions docs/widgets/badge.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,150 @@
---
title: "Badge"
description: "Documentation for Badge"
---

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 | `String?` | The badge's fill color (hex string). Defaults to `ColorScheme.error` from theme. |
| textColor | `String?` | 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 | `Map<String, dynamic>?` | 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 | `Map<String, dynamic>?` | The widget that the badge is stacked on top of. Typically an Icon or IconButton. |

## Example JSON

### Basic Badge with Label

```json
{
"type": "badge",
"label": {
"type": "text",
"data": "5"
},
"child": {
"type": "icon",
"icon": "notifications",
"size": 32
},
"backgroundColor": "#F44336",
"textColor": "#FFFFFF"
}
```

### Badge with Count

```json
{
"type": "badge",
"count": 5,
"child": {
"type": "icon",
"icon": "shopping_cart",
"size": 32
}
}
```

### Badge with Count Exceeding MaxCount

```json
{
"type": "badge",
"count": 1000,
"maxCount": 99,
"child": {
"type": "icon",
"icon": "notifications",
"size": 32
}
}
```

### Small Badge (No Label)

```json
{
"type": "badge",
"smallSize": 8,
"backgroundColor": "#F44336",
"child": {
"type": "icon",
"icon": "circle",
"size": 32
}
}
```

### Badge on IconButton

```json
{
"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"
}
}
}
```

### Badge with Custom Styling

```json
{
"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
}
}
```
210 changes: 210 additions & 0 deletions examples/stac_gallery/assets/json/badge_example.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,210 @@
{
"type": "scaffold",
"appBar": {
"type": "appBar",
"title": {
"type": "text",
"data": "Badge"
}
},
"body": {
"type": "column",
"mainAxisAlignment": "center",
"crossAxisAlignment": "center",
"children": [
{
"type": "text",
"data": "Badge with Label",
"style": {
"fontSize": 18,
"fontWeight": "bold"
}
},
{
"type": "sizedBox",
"height": 16
},
{
"type": "row",
"mainAxisAlignment": "center",
"crossAxisAlignment": "center",
"children": [
{
"type": "badge",
"label": {
"type": "text",
"data": "5"
},
"child": {
"type": "icon",
"icon": "notifications",
"size": 32
}
},
{
"type": "sizedBox",
"width": 24
},
{
"type": "badge",
"label": {
"type": "text",
"data": "NEW"
},
"backgroundColor": "#4CAF50",
"textColor": "#FFFFFF",
"child": {
"type": "icon",
"icon": "mail",
"size": 32
}
}
]
},
{
"type": "sizedBox",
"height": 32
},
{
"type": "text",
"data": "Badge with Count",
"style": {
"fontSize": 18,
"fontWeight": "bold"
}
},
{
"type": "sizedBox",
"height": 16
},
{
"type": "row",
"mainAxisAlignment": "center",
"crossAxisAlignment": "center",
"children": [
{
"type": "badge",
"count": 5,
"child": {
"type": "icon",
"icon": "shopping_cart",
"size": 32
}
},
{
"type": "sizedBox",
"width": 24
},
{
"type": "badge",
"count": 99,
"maxCount": 99,
"child": {
"type": "icon",
"icon": "favorite",
"size": 32
}
},
{
"type": "sizedBox",
"width": 24
},
{
"type": "badge",
"count": 1000,
"maxCount": 99,
"child": {
"type": "icon",
"icon": "notifications",
"size": 32
}
}
]
},
{
"type": "sizedBox",
"height": 32
},
{
"type": "text",
"data": "Small Badge (No Label)",
"style": {
"fontSize": 18,
"fontWeight": "bold"
}
},
{
"type": "sizedBox",
"height": 16
},
{
"type": "row",
"mainAxisAlignment": "center",
"crossAxisAlignment": "center",
"children": [
{
"type": "badge",
"smallSize": 8,
"backgroundColor": "#F44336",
"child": {
"type": "icon",
"icon": "circle",
"size": 32
}
},
{
"type": "sizedBox",
"width": 24
},
{
"type": "badge",
"smallSize": 12,
"backgroundColor": "#4CAF50",
"child": {
"type": "icon",
"icon": "check_circle",
"size": 32
}
}
]
},
{
"type": "sizedBox",
"height": 32
},
{
"type": "text",
"data": "Badge on IconButton",
"style": {
"fontSize": 18,
"fontWeight": "bold"
}
},
{
"type": "sizedBox",
"height": 16
},
{
"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"
}
}
}
]
}
}
23 changes: 23 additions & 0 deletions examples/stac_gallery/assets/json/home_screen.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
}
}
},

{
"type": "listTile",
"leading": {
Expand All @@ -44,6 +45,28 @@
}
}
},
{
"type": "listTile",
"leading": {
"type": "icon",
"icon": "badge"
},
"title": {
"type": "text",
"data": "Stac Badge"
},
"subtitle": {
"type": "text",
"data": "Display small status descriptors, counts, or notifications"
},
"onTap": {
"actionType": "navigate",
"widgetJson": {
"type": "exampleScreen",
"assetPath": "assets/json/badge_example.json"
}
}
},
{
"type": "listTile",
"leading": {
Expand Down
Loading