Feedback@knitui/components

Alert

Alert is a feedback panel composed from Box + Text. Accent comes from the theme prop + palette ramp (never a color prop). variant picks the fill, size sets token-driven spacing/type metrics, and radius the rounding. Optional title, icon and a withCloseButton/onClose affordance. It carries role="alert" with aria-labelledby/aria-describedby wired to the title and body.

WebiOSAndroid6 style slots5 own props15 examples

Stories Source Tests Open in Storybook

import { Alert } from "@knitui/components";

Usage

An Alert is inline and static: it sits in the layout next to whatever it is about and stays until the content changes.

import { Alert } from "@knitui/components";

<Alert title="Payment failed" theme="red">
  Your card was declined. Try another payment method.
</Alert>;

Severity is expressed through the theme, not a separate severity prop — theme="red" / "yellow" / "green" / "blue" recolour the whole block from the palette ramp, the same vocabulary every other component uses.

Add icon for a leading glyph, and withCloseButton with an onClose when the message is dismissible. For full control over the layout, compose the parts directly (see the Compound Parts example below).

When to use something else

A transient message that appears over the UI and leaves on its own → Notification
Validation text belonging to one field → the error prop on the input itself (e.g. TextInput)
A blocking message that needs a decision → Modal

Examples

Variants

Every visual variant stacked.

Loading example…

VariantsSource Storybook

Sizes

Every size on the full token scale.

Loading example…

SizesSource Storybook

With Title

A title is rendered bold above the body and wired as the alert's label.

Loading example…

With TitleSource Storybook

With Icon

An icon sits in a column beside the body.

Loading example…

With IconSource Storybook

With Close Button

A close button pinned top-right; wire onClose to dismiss.

Loading example…

With Close ButtonSource Storybook

Radius

Rounded corners via the radius prop.

Loading example…

RadiusSource Storybook

Themed

The palette ramp follows the active theme — same alert, different accent.

Loading example…

ThemedSource Storybook

Compound Parts

Alert.Title and Alert.Message are the compound parts the default layout composes — usable directly for fully custom alert bodies.

Loading example…

Compound PartsSource Storybook

Gradient

The gradient variant fills the panel with a linear gradient. With no gradient prop it follows the theme ramp; otherwise it accepts a two-color shorthand, $colorN tokens, or a multi-step stops list. Text renders white.

Loading example…

GradientSource Storybook

Gradient Presets

A set of curated multi-color gradient presets.

Loading example…

Gradient PresetsSource Storybook

Gradient Themed

The themed gradient (no gradient prop) derives its ramp from the active theme.

Loading example…

Gradient ThemedSource Storybook

Gradient Angles

The same two-color gradient swept across a range of angles.

Loading example…

Gradient AnglesSource Storybook

Shadows

Optional elevation via the shadow prop — the shared ladder from xs to xl.

Loading example…

ShadowsSource Storybook

Styles

Per-slot styles targets individual parts — here the title and message.

Loading example…

StylesSource Storybook

Props

Prop	Type	Default	Description
`closeButtonLabel`	`string \| undefined`	`"Close"`	`aria-label` for the close button.
`disabled` system	`boolean \| undefined`	—	—
`gradient` system	`GradientValue \| undefined`	—	Gradient fill for variant='gradient' — { from, to, deg } or { stops, deg }.
`icon`	`ReactNode`	—	Icon displayed in a column next to the body.
`onClose`	`(() => void) \| undefined`	—	Called when the close button is pressed.
`radius` system	`string \| number \| undefined`	—	Theme radius token (e.g. `$sm`) or any CSS value.
`shadow` system	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "xxs" \| "xxl" \| undefined` unset · xs · sm · md · lg · xl	—	Elevation — drop shadow from the shared ladder.
`size` system	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "xxs" \| "xxl" \| undefined` xxs · xs · sm · md · lg · xl · xxl	—	Token size for panel spacing, content gaps, text, and close button metrics.
`styles` system	`SlotStyles<AlertStyles> \| undefined`	—	Per-slot style sugar — props spread onto the matching styled part.
`theme` system	`ThemeName \| null \| undefined` unset · blue · red · green · yellow · pink	—	Applies a theme to this element
`title`	`ReactNode`		Alert title, rendered bold above the body.
`variant` system	`"light" \| "outline" \| "white" \| "transparent" \| "default" \| "filled" \| "gradient" \| undefined` filled · light · outline · default · transparent · white · gradient	`light`	Visual fill — how the theme color ramp is applied.
`withCloseButton`	`boolean \| undefined`	`false`	Show a close button pinned to the top-right.

Style slots

Every part of Alert can be styled through the styles prop. Explicit props on the component always win over slot styles.

Slot	Targets
`body`	Props for the body column that holds title + message (`.Body`).
`closeButton`	Props spread onto the close button (under `closeButtonLabel`).
`content`	Props for the content column (rich, non-text children) (`.Content`).
`icon`	Props for the icon column wrapper (`.Icon`).
`message`	Props for the message text (text-only children) (`.Message`).
`title`	Props for the title text (`.Title`).

Accessibility & DOM props (2)

Prop	Type
`key`	`Key \| null \| undefined`
`ref`	`Ref<TamaguiElement> \| undefined`

Plus 498 inherited style props from Box — the full Tamagui/React Native style surface, including token shorthands like p, mx, bg and c. See Tokens for the scales they accept, or the full list.

Accessibility

The container renders with role="alert", so assistive technology announces it as soon as it appears — without moving focus.

Naming is wired automatically: when you pass title it gets a generated id and becomes the block's aria-labelledby target, and the body is referenced through aria-describedby. Title and message are announced together.

role="alert" is an interruption. It is correct for something that just happened and the user must know about. For a message that is simply present on the page — a persistent tip or a static notice — the announcement is noise; render the content in a plain Paper or Card instead.
Because it announces on appearance, mount an Alert when the state changes rather than rendering it hidden and revealing it with styles — a hidden-then-shown alert may never be announced.
The close button takes its accessible name from closeButtonLabel (default "Close"); override it when the alert's subject makes a more specific label clearer.
Don't rely on colour alone to carry severity: the title or icon should make the meaning explicit for anyone who can't distinguish the theme.