# Badge

- Entry point: `@koobiq/components/badge`
- NgModule: `KbqBadgeModule`
- Page: https://koobiq.io/en/components/badge/overview

## Overview

A badge is used to highlight the status, count, or other important characteristics of an object.

### Properties

#### Style

**Example: Badge fill and style** (`badge-overview`)

```ts badge-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqBadgeColors, KbqBadgeModule } from '@koobiq/components/badge';

@Component({
    selector: 'badge-overview-example',
    imports: [
        KbqBadgeModule
    ],
    templateUrl: 'badge-overview-example.html',
    styleUrls: ['badge-overview-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class BadgeOverviewExample {
    colors = KbqBadgeColors;
}
```

```html badge-overview-example.html
<div class="example-badge-fill-and-style">
    <div class="layout-row layout-gap-l">
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Theme</div>
            <kbq-badge [badgeColor]="colors.Theme">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Error</div>
            <kbq-badge [badgeColor]="colors.Error">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Warning</div>
            <kbq-badge [badgeColor]="colors.Warning">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Success</div>
            <kbq-badge [badgeColor]="colors.Success">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Contrast</div>
            <kbq-badge [badgeColor]="colors.Contrast">Badge</kbq-badge>
        </div>
    </div>

    <div class="layout-row layout-gap-l">
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Fade Theme</div>
            <kbq-badge [badgeColor]="colors.FadeTheme">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Fade Error</div>
            <kbq-badge [badgeColor]="colors.FadeError">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Fade Warning</div>
            <kbq-badge [badgeColor]="colors.FadeWarning">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Fade Success</div>
            <kbq-badge [badgeColor]="colors.FadeSuccess">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Fade Contrast</div>
            <kbq-badge [badgeColor]="colors.FadeContrast">Badge</kbq-badge>
        </div>
    </div>

    <div class="layout-row layout-gap-l">
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Outline Fade Theme</div>
            <kbq-badge [badgeColor]="colors.FadeTheme" [outline]="true">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Outline Fade Error</div>
            <kbq-badge [badgeColor]="colors.FadeError" [outline]="true">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Outline Fade Warning</div>
            <kbq-badge [badgeColor]="colors.FadeWarning" [outline]="true">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Outline Fade Success</div>
            <kbq-badge [badgeColor]="colors.FadeSuccess" [outline]="true">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Outline Fade Contrast</div>
            <kbq-badge [badgeColor]="colors.FadeContrast" [outline]="true">Badge</kbq-badge>
        </div>
    </div>
    <div class="layout-row layout-gap-l">
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Disabled</div>
            <kbq-badge [badgeColor]="colors.Disabled">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Outline Disabled</div>
            <kbq-badge [badgeColor]="colors.Disabled" [outline]="true">Badge</kbq-badge>
        </div>
    </div>
</div>
```

```css badge-overview-example.css
.example-badge-fill-and-style {
    display: flex;
    flex-direction: column;
    gap: 20px;
    min-width: calc(100px * 5 + 16px * 4);
}

.example-badge-fill-and-style__badge-label {
    color: var(--kbq-foreground-contrast-secondary);
    margin-bottom: 8px;
}

.example-badge-fill-and-style__badge {
    width: 100px;
}
```

#### Size

**Example: Badge size** (`badge-size`)

```ts badge-size-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqBadgeColors, KbqBadgeModule } from '@koobiq/components/badge';

@Component({
    selector: 'badge-size-example',
    imports: [
        KbqBadgeModule
    ],
    template: `
        <div class="layout-row layout-gap-l">
            <kbq-badge [badgeColor]="colors.Success">Normal</kbq-badge>
            <kbq-badge [badgeColor]="colors.Success" [compact]="true">Compact</kbq-badge>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class BadgeSizeExample {
    colors = KbqBadgeColors;
}
```

#### Content

**Example: Badge content** (`badge-content`)

```ts badge-content-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqBadgeColors, KbqBadgeModule } from '@koobiq/components/badge';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'badge-content-example',
    imports: [
        KbqBadgeModule,
        KbqIconModule
    ],
    template: `
        <div class="layout-row layout-gap-l">
            <kbq-badge [badgeColor]="colors.Success">Normal</kbq-badge>
            <kbq-badge [badgeColor]="colors.Success">
                Normal
                <div class="kbq-badge-caption">0.8</div>
            </kbq-badge>
            <kbq-badge [badgeColor]="colors.Success">
                <i kbq-icon="kbq-cloud-o_16"></i>
                Normal
            </kbq-badge>
            <kbq-badge [badgeColor]="colors.Success">
                Normal
                <i kbq-icon="kbq-cloud-o_16"></i>
            </kbq-badge>
            <kbq-badge [badgeColor]="colors.Success">
                <i kbq-icon="kbq-cloud-o_16"></i>
                Normal
                <div class="kbq-badge-caption">0.8</div>
                <i kbq-icon="kbq-cloud-o_16"></i>
            </kbq-badge>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class BadgeContentExample {
    colors = KbqBadgeColors;
}
```

### Usage examples

#### Badge list

Badges can be displayed in a row or in a column.

**Example: Badge list** (`badge-list`)

```ts badge-list-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqBadgeColors, KbqBadgeModule } from '@koobiq/components/badge';

@Component({
    selector: 'badge-list-example',
    imports: [
        KbqBadgeModule
    ],
    template: `
        <div class="badge-list-example">
            <div class="example-badge-list__label kbq-text-compact">Horizontal</div>
            <div class="example-badge-list__list">
                @for (badge of badges; track badge) {
                    <kbq-badge [badgeColor]="badge.color">{{ badge.name }}</kbq-badge>
                }
            </div>
            <div class="example-badge-list__label layout-margin-top-l kbq-text-compact">Vertical</div>
            <div class="example-badge-list__list example-badge-list__list_vertical">
                @for (badge of badges; track badge) {
                    <kbq-badge [badgeColor]="badge.color">{{ badge.name }}</kbq-badge>
                }
            </div>
        </div>
    `,
    styleUrls: ['badge-list-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class BadgeListExample {
    colors = KbqBadgeColors;

    badges: { name: string; color: string }[] = [
        { name: 'Bruteforce', color: this.colors.FadeContrast },
        { name: 'Complex Attack', color: this.colors.FadeContrast },
        { name: 'DDoS', color: this.colors.FadeContrast },
        { name: 'DoS', color: this.colors.FadeContrast },
        { name: 'HIPS Alert', color: this.colors.FadeContrast },
        { name: 'IDS/IPS Alert', color: this.colors.FadeContrast },
        { name: 'Identity Theft', color: this.colors.FadeContrast },
        { name: 'Miscellaneous', color: this.colors.FadeContrast },
        { name: 'Network Attack', color: this.colors.FadeContrast },
        { name: 'Post Compromise', color: this.colors.FadeContrast }
    ];
}
```

```css badge-list-example.css
.example-badge-list__list {
    display: flex;
    flex-wrap: wrap;
    gap: 4px;
    margin-top: 10px;
}

.example-badge-list__list_vertical {
    flex-direction: column;
    align-items: flex-start;
}

.example-badge-list__label {
    color: var(--kbq-foreground-contrast-secondary);
}
```

#### Tooltip with explanation

On hover or focus, a tooltip with an explanation or additional information can be shown.

**Example: Badge tooltip** (`badge-tooltip`)

```ts badge-tooltip-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqBadgeColors, KbqBadgeModule } from '@koobiq/components/badge';
import { PopUpPlacements } from '@koobiq/components/core';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

@Component({
    selector: 'badge-tooltip-example',
    imports: [
        KbqBadgeModule,
        KbqToolTipModule
    ],
    template: `
        <div class="example-badge-tooltip">
            <kbq-badge
                [badgeColor]="colors.FadeContrast"
                [kbqPlacement]="PopUpPlacements.Top"
                [kbqTooltipArrow]="false"
                [kbqTooltip]="tooltipText"
            >
                DoS
            </kbq-badge>
        </div>
    `,
    styleUrls: ['badge-tooltip-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class BadgeTooltipExample {
    colors = KbqBadgeColors;
    protected readonly PopUpPlacements = PopUpPlacements;

    tooltipText =
        'DoS (аббр. англ. denial-of-service attack «отказ в обслуживании») — хакерская атака на вычислительную систему с целью довести ее до отказа, то есть создание таких условий, при которых добросовестные пользователи системы не смогут получить доступ к предоставляемым системным ресурсам (серверам), либо этот доступ будет затруднен';
}
```

```css badge-tooltip-example.css
.example-badge-tooltip {
    display: flex;
    justify-content: center;

    kbq-badge {
        cursor: help;
    }
}
```

#### In a table

The label inside the badge is aligned to the text baseline in a table.

**Example: Badge table** (`badge-table`)

```ts badge-table-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqBadgeColors, KbqBadgeModule } from '@koobiq/components/badge';
import { KbqLink } from '@koobiq/components/link';
import { KbqTableModule } from '@koobiq/components/table';

@Component({
    selector: 'badge-table-example',
    imports: [
        KbqBadgeModule,
        KbqLink,
        KbqTableModule
    ],
    templateUrl: 'badge-table-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class BadgeTableExample {
    colors = KbqBadgeColors;
}
```

```html badge-table-example.html
<table kbq-table class="docs-table-example badge-table-example">
    <thead>
        <tr>
            <th style="width: 33.3%">Столбец 1</th>
            <th style="width: 33.3%">Столбец 2</th>
            <th style="width: 33.3%">Столбец 3</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Значение</td>
            <td><kbq-badge [badgeColor]="colors.FadeContrast">Badge</kbq-badge></td>
            <td>EXT. Использование фишинговых ресурсов (phishingAttacks)</td>
        </tr>
        <tr>
            <td>
                <a kbqLink href="https://koobiq.io/en/components/badge">Ссылка</a>
                &nbsp;
                <kbq-badge [badgeColor]="colors.FadeContrast" [compact]="true">Badge</kbq-badge>
            </td>
            <td>
                Обнаружена попытка получить список процессов, запущенных в системе, на узле
                qa-kolobok.mpqa.rd.koobiq.com
            </td>
            <td>
                <kbq-badge [badgeColor]="colors.FadeSuccess" [outline]="true">Badge</kbq-badge>
            </td>
        </tr>
    </tbody>
</table>
```

### Recommendations

- Badges can be used on their own, while [tags](https://koobiq.io/en/components/tag.md) are more often part of other controls: [Select](https://koobiq.io/en/components/select.md#multiple-selection), [Tag autocomplete](https://koobiq.io/en/components/tag-autocomplete.md), [Tag input](https://koobiq.io/en/components/tag-input.md).
- Don't overuse badges: the screen quickly turns into a colorful garland and emphasis is lost.
- A list of tags can draw excessive attention. Elements can be displayed separated by commas, interpuncts, or small indentation.

## API

### Components

#### KbqBadge (component)

Component used to highlight the status, count or another important characteristic of an object.

```ts
@Component({ selector: 'kbq-badge' })
class KbqBadge {
    readonly compact = input<boolean>(false);
    readonly outline = input<boolean>(false);
    readonly badgeColor = input<string>(KbqBadgeColors.FadeContrast);
}
```

- `[compact]`: `boolean` — Whether the badge uses the compact size.
- `[outline]`: `boolean` — Whether the badge is outlined instead of filled.
- `[badgeColor]`: `string` — Color of the badge. An empty, `null` or `undefined` value falls back to the default, so a read of the
  signal reports the color the badge actually renders in. Defaults to `'fade-contrast'`.

### Directives

#### KbqBadgeCaption (directive)

Directive that marks the caption part of a badge.

```ts
@Directive({ selector: '[kbq-badge-caption]' })
class KbqBadgeCaption {}
```

### Enums

#### KbqBadgeColors (enum)

Colors supported by the badge.

```ts
enum KbqBadgeColors {
    FadeContrast = 'fade-contrast',
    FadeTheme = 'fade-theme',
    FadeSuccess = 'fade-success',
    FadeWarning = 'fade-warning',
    FadeError = 'fade-error',
    Contrast = 'contrast',
    Theme = 'theme',
    Success = 'success',
    Warning = 'warning',
    Error = 'error',
    Disabled = 'disabled'
}
```