# @asphalt-react/flag

> Flag

Latest version **2.17.1** (published 2026-08-31) · UNLICENSED license · 0 weekly downloads

## Install

```sh
npm install @asphalt-react/flag
pnpm add @asphalt-react/flag
yarn add @asphalt-react/flag
bun add @asphalt-react/flag
```

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 2.17.1 |
| Published | 2026-08-31 |
| First published | 2022-03-30 |
| Weekly downloads | 0 |
| License | UNLICENSED |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 6 |
| Unpacked size | 69.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | UX Engineering - Web |
| Maintainers | sayantan1211, dawn29, antoniomontana, goto.abhinav, elayudhanira-gojek, yessyprmtsr, soorajj |
| Keywords | asphalt, flag, component, dls, design language system |

## Links

- npm: https://www.npmjs.com/package/@asphalt-react/flag
- npm.io page: https://npm.io/package/@asphalt-react/flag

## Dependencies (6)

- [classnames](https://npm.io/package/classnames.md) ^2.5.1
- [prop-types](https://npm.io/package/prop-types.md) ^15.8.1
- [@asphalt-react/button](https://npm.io/package/@asphalt-react/button.md) ^2.16.0
- [@asphalt-react/helper](https://npm.io/package/@asphalt-react/helper.md) ^2.16.0
- [@asphalt-react/iconpack](https://npm.io/package/@asphalt-react/iconpack.md) ^2.16.0
- [@asphalt-react/svg-normalizer](https://npm.io/package/@asphalt-react/svg-normalizer.md) ^2.16.0

## Recent versions

- 2.17.1 (latest) — 2026-08-31
- 2.0.0-alpha.29 (next) — 2023-12-15
- 2.16.0 — 2026-07-28
- 2.15.3 — 2026-07-07
- 2.15.1 — 2026-04-28
- 2.15.0 — 2026-04-13
- 2.14.0 — 2026-03-11
- 2.13.0 — 2026-02-19
- 2.12.2 — 2026-01-28
- 2.12.1 — 2025-12-19
- 2.12.0 — 2025-11-28
- 2.11.0 — 2025-11-10
- 2.10.0 — 2025-10-27
- 2.9.0 — 2025-10-02
- 2.8.1 — 2025-09-10
- … 35 more at https://npm.io/package/@asphalt-react/flag/versions

## README

# Flag

![npm](https://img.shields.io/npm/dt/@asphalt-react/flag?style=flat-square)
[![npm version](https://badge.fury.io/js/@asphalt-react%2Fflag.svg)](https://badge.fury.io/js/@asphalt-react%2Fflag)

Flag component is used to provide any information from the application to the user. They should be used for successful, cautious, destructive kind of messages. Flags can be inlined, floated, embedded or shown as a banner.

## Usage

```jsx
import {
  InlineFlag,
  FloatingFlag,
  BannerFlag,
  PageFlag
} from "@asphalt-react/flag"

<InlineFlag success>
  Email format is incorrect
</InlineFlag>

<FloatingFlag title="Remove user?" danger>
  This action is irreversible
</FloatingFlag>

<BannerFlag title="Policy changes" warning>
  Tax rules are changing in the next month
</BannerFlag>

<PageFlag title="We don't spam" neutral>
  We will only send you useful emails
</PageFlag>
```

## Variants

There are four variants of Flags, each available as named exports:

1. **InlineFlag**: Used to show information related to form fields, for example, a validation error.

2. **FloatingFlag**: Used for showing alerts or toasts. Floating flags are responsive to viewport sizes. Floating flags have support intent background color by default.

3. **BannerFlag**: Used to show information that demands more user attention. It adjusts to the container's width always.

4. **PageFlag**: Used to show contextual background information for filling a form. Embeds the Flag into the page and adjusts to the container's width.

## Intents

All Flags support multiple support intents:

* **info** (default): a generic information
* **success**: information with successful intent
* **warning**: information with warning intent; demands more attention that info
* **danger**: critical information that demands the most attention. Used for information leading to destructive actions like removing a user.
* **neutral**: information that demands least user attention
* **invalid**: used to show form field error messages; applicable for "inline" variant only.

### Competing intents

If a Flag receives multiple intents, it fallbacks to the "info" intent. For example:

```jsx
<PageFlag warning danger title="Required fields">
  All fields are mandatory
</PageFlag>
```

This will render a Page flag with "info" intent.

## Hooks

Create toast notifications with the `FloatingFlag` component and the `useToast` hook. Toasts display temporary, dismissible messages to users.

### useToast

```jsx
import React from "react"
import { Button } from "@asphalt-react/button"
import { FloatingFlag, useToast } from "@asphalt-react/flag"

function ToastDemo() {
  const { visible, show, hide } = useToast()
  return (
    <>
      <style>{`
        .toastPanel {
          position: fixed;
          z-index: 1;
          right: 0;
          top: 0;
          padding: 1rem;
          margin-bottom: 1rem;
          visibility: hidden;
          opacity: 0;
          transform: translateX(340px);
          transition: opacity 0.5s ease-in-out, visibility 0.5s ease-in-out, transform 0.5s ease-in-out;
        }
        .toastPanel.visible {
          visibility: visible;
          opacity: 1;
          transform: translateX(0);
        }
      `}</style>
      <Button onClick={show}>Show Toast</Button>
      <div className={`toastPanel${visible ? ' visible' : ''}`}>
        <FloatingFlag success title="Success" onDismiss={hide}>
          That was a successful demo
        </FloatingFlag>
      </div>
    </>
  )
}
```

This example shows how to trigger a toast message with a button. The toast will appear and can be dismissed by the user.

## Purposeful Areas

Flags is composed of predefined areas to serve a particular purpose. They adapt to different variants and intents.

* **Title** - a brief one-line message.
* **Description** - main content of the flag.
* **Icon** - a qualifier SVG according to the variant; can be overridden with a custom SVG
* **Action** - a container for actionable elements like  buttons or links.
* **Dismiss** - a button to dismiss the flag. Renders by default in all flags except "inline" variant

> InlineFlag only has icon and text in them and they are not dismissible.

## Positioning in Banner and Page variants

Icon & Title can be center aligned when there is no description and action area. Actions render in the start of the flag. They can be moved to the end as well.

[comment]: #usage

# InlineFlag

[comment]: # "InlineFlag Props"

## Props

### children

React node for the main content.

| type | required | default |
| ---- | -------- | ------- |
| node | false    | null    |

### icon

To override the default qualifier icon. Pass `false` to hide it.

Accepts SVG.

| type  | required | default |
| ----- | -------- | ------- |
| union | false    | null    |

### size

Size of the flag, controls the icon and text size.

| type | required | default |
| ---- | -------- | ------- |
| enum | false    | "m"     |

### info

Enables the info intent.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### success

Enables the success intent.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### danger

Enables the danger intent.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### warning

Enables the warning intent.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### neutral

Enables the neutral intent.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### invalid

Enables the invalid intent.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

# FloatingFlag

[comment]: # "FloatingFlag Props"

## Props

### children

React node for the description content.

| type | required | default |
| ---- | -------- | ------- |
| node | false    | null    |

### title

React node for the title content.

| type | required | default |
| ---- | -------- | ------- |
| node | false    | null    |

### icon

To override the default qualifier icon. Pass `false` to hide it.

Accepts SVG.

| type  | required | default |
| ----- | -------- | ------- |
| union | false    | null    |

### actions

List of actionable elements.

| type | required | default |
| ---- | -------- | ------- |
| node | false    | null    |

### info

Enables the info intent.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### success

Enables the success intent.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### danger

Enables the danger intent.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### warning

Enables the warning intent.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### neutral

Enables the neutral intent.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### inverse

Enables the inverse intent.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### highlight

Adds a support intent background color to make the flag prominent.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | true    |

### onDismiss

Callback for dismiss action.

| type | required | default |
| ---- | -------- | ------- |
| func | false    | N/A     |

### dismiss

Enables the dismiss action.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | true    |

# BannerFlag

[comment]: # "BannerFlag Props"

## Props

### children

React node for the description content.

| type | required | default |
| ---- | -------- | ------- |
| node | false    | null    |

### title

React node for the title content.

| type | required | default |
| ---- | -------- | ------- |
| node | false    | null    |

### titleCenter

Centers the title horizontally.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### icon

To override the default qualifier icon. Pass `false` to hide it.

Accepts SVG.

| type  | required | default |
| ----- | -------- | ------- |
| union | false    | null    |

### actions

List of actionable elements.

| type    | required | default |
| ------- | -------- | ------- |
| element | false    | null    |

### actionsEnd

Positions the actionable element towards the end of the container

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### info

Enables the info intent.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### success

Enables the success intent.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### danger

Enables the danger intent.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### warning

Enables the warning intent.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### neutral

Enables the neutral intent.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### dismiss

Enables the dismiss action.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | true    |

### onDismiss

Callback for the dismiss action.

| type | required | default |
| ---- | -------- | ------- |
| func | false    | N/A     |

# PageFlag

[comment]: # "PageFlag Props"

## Props

### children

React node for the description content.

| type | required | default |
| ---- | -------- | ------- |
| node | false    | null    |

### title

React node for the title content.

| type | required | default |
| ---- | -------- | ------- |
| node | false    | null    |

### titleCenter

Centers the title horizontally.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### icon

To override the default qualifier icon. Pass `false` to hide it.

Accepts SVG.

| type  | required | default |
| ----- | -------- | ------- |
| union | false    | null    |

### actions

List of actionable elements.

| type    | required | default |
| ------- | -------- | ------- |
| element | false    | null    |

### actionsEnd

Positions the actionable element towards the end of the container

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### info

Enables the info intents.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### success

Enables the success intents.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### danger

Enables the danger intents.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### warning

Enables the warning intents.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### neutral

Enables the neutral intents.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### dismiss

Renders a dismiss button.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | true    |

### onDismiss

Callback for dismiss action.

| type | required | default |
| ---- | -------- | ------- |
| func | false    | null    |

### rounded

Adds a border-radius to the flag.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | true    |

---
_Source: https://npm.io/package/@asphalt-react/flag · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._