Badge
Usage
HLBadge is a wrapper used along with other components such as HLAvatar or HLButton to display a count or indicate a change.
Basic Usage
Wraps a child element and displays a count, applying max to cap the displayed number.
<template>
<HLBadge id="basic-badge" :value="400" :max="15">
<HLAvatar :round="false" size="sm">Small</HLAvatar>
</HLBadge>
</template>
<script setup lang="ts">
import { HLBadge, HLAvatar } from '@platform-ui/highrise'
</script>Colors
Sets the badge background using the color prop.
<template>
<HLBadge id="color-badge" :value="40" color="blue">
<HLAvatar :round="false" size="sm">Small</HLAvatar>
</HLBadge>
</template>
<script setup lang="ts">
import { HLBadge, HLAvatar } from '@platform-ui/highrise'
</script>Dot Badge
Renders a small dot instead of a value when the dot prop is set.
<template>
<HLBadge id="dot-badge" dot>
<HLAvatar :round="false" size="sm">Small</HLAvatar>
</HLBadge>
</template>
<script setup lang="ts">
import { HLBadge, HLAvatar } from '@platform-ui/highrise'
</script>Processing State
Adds an animated pulse to the badge when the processing prop is set.
<template>
<HLBadge id="processing-badge" :value="40" processing>
<HLAvatar :round="false" size="sm">Small</HLAvatar>
</HLBadge>
</template>
<script setup lang="ts">
import { HLBadge, HLAvatar } from '@platform-ui/highrise'
</script>Sizes
Controls the badge dimensions via the size prop, ranging from 3xs to lg.
<template>
<HLBadge id="size-badge" :value="60" size="3xs">
<HLAvatar :round="false" size="sm">3xs</HLAvatar>
</HLBadge>
<HLBadge id="size-badge" :value="60" size="2xs">
<HLAvatar :round="false" size="sm">2xs</HLAvatar>
</HLBadge>
<HLBadge id="size-badge" :value="60" size="xs">
<HLAvatar :round="false" size="sm">xs</HLAvatar>
</HLBadge>
<HLBadge id="size-badge" :value="60" size="sm">
<HLAvatar :round="false" size="sm">sm</HLAvatar>
</HLBadge>
<HLBadge id="size-badge" :value="60" size="md">
<HLAvatar :round="false" size="sm">md</HLAvatar>
</HLBadge>
<HLBadge id="size-badge" :value="60" size="lg">
<HLAvatar :round="false" size="sm">lg</HLAvatar>
</HLBadge>
</template>
<script setup lang="ts">
import { HLBadge, HLAvatar } from '@platform-ui/highrise'
</script>Custom Size
Sets size="custom" with offset and a #value slot to fully control badge placement and content.
<template>
<HLBadge id="size-badge" :value="60" size="xs">
<HLAvatar :round="false" size="sm">Small</HLAvatar>
</HLBadge>
</template>
<script setup lang="ts">
import { HLBadge, HLAvatar } from '@platform-ui/highrise'
</script><template>
<HLBadge id="size-badge" :value="60" size="custom" :offset="[0, 29]" dot>
<HLAvatar :round="false" size="sm">Custom</HLAvatar>
<template #value>
<div class="bg-black" :style="{ width: 10 + 'px', height: 10 + 'px', borderRadius: '50%' }"></div>
</template>
</HLBadge>
</template>
<script setup lang="ts">
import { HLBadge, HLAvatar } from '@platform-ui/highrise'
</script>Show Zero
A badge with value="0" renders nothing by default — a zero count is treated as "nothing to report". Set showZero to display it anyway.
<template>
<!-- Zero is hidden (default) -->
<HLBadge id="badge-zero-hidden" :value="0">
<HLAvatar size="sm" src="https://api.dicebear.com/9.x/avataaars/svg?seed=Maria" />
</HLBadge>
<!-- Zero is rendered -->
<HLBadge id="badge-zero-shown" :value="0" show-zero>
<HLAvatar size="sm" src="https://api.dicebear.com/9.x/avataaars/svg?seed=Maria" />
</HLBadge>
</template>
<script setup lang="ts">
import { HLBadge, HLAvatar } from '@platform-ui/highrise'
</script>Border
Set border to draw a white ring around the badge, separating it from whatever sits behind it.
The ring is white, so it only reads against a darker surface — on the default white page it blends in. The demo below is on a dark panel to make the difference visible.
Left: no ring. Middle: border on a count badge. Right: border on a dot badge.
<template>
<!-- No ring (default) -->
<HLBadge id="badge-no-border" :value="5">
<HLAvatar size="sm" src="https://api.dicebear.com/9.x/avataaars/svg?seed=Maria" />
</HLBadge>
<!-- White ring separates the badge from what's behind it -->
<HLBadge id="badge-with-border" :value="5" border>
<HLAvatar size="sm" src="https://api.dicebear.com/9.x/avataaars/svg?seed=Maria" />
</HLBadge>
<!-- Works with dot badges too -->
<HLBadge id="badge-dot-border" dot border color="success">
<HLAvatar size="sm" src="https://api.dicebear.com/9.x/avataaars/svg?seed=Maria" />
</HLBadge>
</template>
<script setup lang="ts">
import { HLBadge, HLAvatar } from '@platform-ui/highrise'
</script>Positioning
Badges sit at the top-right of their content. Use offset — a [x, y] tuple — to move that anchor. Values accept numbers (treated as px) or CSS length strings; positive x moves the badge right, positive y moves it down.
<template>
<!-- Default anchor: top-right -->
<HLBadge id="badge-offset-default" :value="3">
<HLAvatar size="md" src="https://api.dicebear.com/9.x/avataaars/svg?seed=Maria" />
</HLBadge>
<!-- Nudged inward from the top-right corner -->
<HLBadge id="badge-offset-inset" :value="3" :offset="[-6, 6]">
<HLAvatar size="md" src="https://api.dicebear.com/9.x/avataaars/svg?seed=Maria" />
</HLBadge>
<!-- Pushed down to sit near the bottom-right -->
<HLBadge id="badge-offset-bottom" :value="3" :offset="[-6, 40]">
<HLAvatar size="md" src="https://api.dicebear.com/9.x/avataaars/svg?seed=Maria" />
</HLBadge>
</template>
<script setup lang="ts">
import { HLBadge, HLAvatar } from '@platform-ui/highrise'
</script>INFO
offset is the only positioning prop. There is no named-corner shorthand — to anchor a badge to a different corner, offset it by roughly the size of the content it wraps, as the third example does.
Controlling Visibility
show toggles the badge without unmounting the content it wraps. Use it to hide the indicator while keeping the avatar, button, or icon in place.
<template>
<!-- Badge visible (default) -->
<HLBadge id="badge-show-true" :value="7" :show="true">
<HLAvatar size="sm" src="https://api.dicebear.com/9.x/avataaars/svg?seed=Maria" />
</HLBadge>
<!-- Badge hidden; the avatar still renders -->
<HLBadge id="badge-show-false" :value="7" :show="false">
<HLAvatar size="sm" src="https://api.dicebear.com/9.x/avataaars/svg?seed=Maria" />
</HLBadge>
</template>
<script setup lang="ts">
import { HLBadge, HLAvatar } from '@platform-ui/highrise'
</script>Custom Content
Renders arbitrary markup, such as an icon, inside the badge via the #value slot.
<template>
<HLBadge id="custom-badge" size="xs" :offset="[0, 10]" color="blue">
<HLAvatar size="sm" src="https://api.dicebear.com/9.x/avataaars/svg?seed=Maria"></HLAvatar>
<template #value>
<ArrowDownIcon class="text-primary-600 w-3 h-3" />
</template>
</HLBadge>
</template>
<script setup lang="ts">
import { HLBadge, HLAvatar } from '@platform-ui/highrise'
import { ArrowDownIcon } from '@gohighlevel/ghl-icons/24/outline'
</script>Accessibility
- When the badge conveys data, expose it via
aria-label(“3 unread messages”); decorative badges should remainaria-hidden="true". - Wrap live counts inside
aria-live="polite"so updates announce without stealing focus.
Imports
import { HLBadge } from '@platform-ui/highrise'Props
| Name | Type | Default | Description |
|---|---|---|---|
| id * | string | undefined | undefined | The id of the element |
| color | 'gray' | 'primary' | 'success' | 'error' | 'warning' | 'gray-blue' | 'blue-light' | 'blue' | 'indigo' | 'purple' | 'pink' | 'rose' | 'orange-dark' | 'red' | Color variant of the badge |
| dot | boolean | false | Show as a dot badge |
| max | number | 99 | Cap for a numeric value; anything above renders as {max}+ |
| processing | boolean | false | Show processing animation |
| showZero | boolean | false | Whether to show zero value |
| show | boolean | true | Control badge visibility |
| value | number | string | undefined | undefined | Value to display in badge |
| offset | [number | string, number | string] | undefined | undefined | [x, y] shift from the default top-right anchor. Numbers are px; CSS length strings also work |
| size | 'xs' | 'sm' | 'md' | 'lg' | '2xs' | '3xs' | 'custom' | 'md' | Size of the badge |
| border | boolean | false | Render a ring border around the badge |
Slots
| Name | Parameters | Description |
|---|---|---|
| default | () | The default content slot |
| value | () | Custom value content slot |