Alert

The Alert component displays a short, important message in a way that attracts the user's attention without interrupting their task.

Installation

$ cbui-cli install alert

To get started, please make sure you have installed cbui-cli globally and authenticated your account. This will ensure you can access all the necessary features.

View documents

Import

index.tsx

import { Alert } from '@/crossbuildui/alert';
// import Icon from 'react-native-vector-icons/MaterialIcons'; // Or your preferred icon library

Alert Component

Basic Usage

Provide a title and optionally a description.

MyComponent.tsx

<Alert
  title="System Update Available"
  description="A new version of the software is ready to be installed."
/>

Variants

Alerts support multiple visual variant options: solid (default), bordered, flat, faded, and glass.

MyComponent.tsx

<View style={{gap: 16}}>
  <Alert title="Solid Alert (Default)" variant="solid" color="primary" />
  <Alert title="Bordered Alert" variant="bordered" color="secondary" description="This alert has a border." />
  <Alert title="Flat Alert" variant="flat" color="success" description="This alert has a flat style." />
  <Alert title="Faded Alert" variant="faded" color="warning" description="This alert has a faded style." />
  <Alert title="Glass Alert" variant="glass" color="primary" description="This alert has a frosted glass effect." />
</View>

Colors

Set the thematic color using the color prop. Supported colors include primary, secondary, success, warning, danger, and default (default).

MyComponent.tsx

<View style={{gap: 16}}>
  <Alert title="Primary Alert" color="primary" description="This is a primary alert." />
  <Alert title="Secondary Alert" color="secondary" description="This is a secondary alert." />
  <Alert title="Success Alert" color="success" description="Operation completed successfully!" />
  <Alert title="Warning Alert" color="warning" description="Please check your input." />
  <Alert title="Danger Alert" color="danger" description="An error occurred!" />
  <Alert title="Default Alert" color="default" description="This is a default alert." />
</View>

Radius

Control the border radius with none, sm, md (default), lg, or full.

MyComponent.tsx

<View style={{gap: 16}}>
  <Alert title="No Radius" radius="none" color="primary" />
  <Alert title="Small Radius" radius="sm" color="secondary" />
  <Alert title="Medium Radius (Default)" radius="md" color="success" />
  <Alert title="Large Radius" radius="lg" color="warning" />
  <Alert title="Full Radius" radius="full" color="danger" />
</View>

Glass Variant

The glass variant applies a frosted glass effect to the alert background using expo-blur. Customize its appearance with glassIntensity (a number from 0 to 100) and glassTint ('light', 'dark', or 'default'). Text and default icon colors for this variant typically adapt to the theme's foreground color.

MyComponent.tsx

<View style={{gap: 16}}>
  <Alert
    title="Light Glass Alert"
    variant="glass"
    glassIntensity={70}
    glassTint="light"
    // color="primary" // color prop has less visual impact on text/bg for glass
    description="This alert uses a light glass effect. Text color defaults to theme foreground."
    isClosable
  />
  <Alert
    title="Dark Glass Alert"
    variant="glass"
    glassIntensity={40}
    glassTint="dark"
    description="This alert uses a dark glass effect with a custom icon."
    // Icon color should be set manually to contrast with the dark blur
    icon={<Icon name="shield" size={20} color="white" />} // Ensure icon color contrasts
  />
</View>

With Icon

Alerts can display a default icon based on their color (for success, warning, danger) or a custom icon. Use hideIcon to remove it.

MyComponent.tsx

// Default icons are shown for success, warning, danger colors.
<View style={{gap: 16}}>
  <Alert title="Success with Default Icon" color="success" />
  <Alert title="Warning with Default Icon" color="warning" />
  <Alert title="Danger with Default Icon" color="danger" />
  <Alert
    title="Custom Icon"
    color="primary"
    icon={<Icon name="info" size={20} color="white" />} // Assuming Icon component
    description="This alert uses a custom info icon."
  />
  <Alert title="Icon Hidden" color="secondary" hideIcon />
</View>

Closable

Set isClosable to true to display a close button. Manage visibility using isVisible and onVisibleChange (or onClose).

MyComponent.tsx

function ClosableAlertExample() {
  const [visible, setVisible] = React.useState(true);

  if (!visible) {
    return (
      <CrossBuildButton onPress={() => setVisible(true)}>
        Show Alert Again
      </CrossBuildButton>
    );
  }

  return (
    <Alert
      title="Closable Alert"
      description="You can close this alert by clicking the 'x' button."
      color="info" // Assuming 'info' is a defined color or maps to 'default'/'primary'
      isClosable
      isVisible={visible}
      onVisibleChange={setVisible} // Or onClose={() => setVisible(false)}
      // Custom close button icon:
      // closeButtonProps={{ icon: <Icon name="cancel" size={22} /> }}
    />
  );
}

Start and End Content

Add custom elements before the icon/text (startContent) or after the text/before the close button (endContent).

MyComponent.tsx

<View style={{gap: 16}}>
  <Alert
    title="Alert with Start Content"
    color="primary"
    startContent={<Icon name="star" size={24} color="gold" />}
    description="This alert has a star at the beginning."
  />
  <Alert
    title="Alert with End Content"
    color="secondary"
    endContent={<CrossBuildButton size="sm" variant="flat" color="secondary">Action</CrossBuildButton>}
    description="This alert has an action button at the end."
  />
  <Alert
    title="Alert with Both"
    color="success"
    startContent={<Icon name="thumb-up" size={20} color="white" />}
    endContent={<Text style={{fontSize: 12, color: 'white'}}>Approved</Text>}
    description="All good here!"
  />
</View>

Controlled Visibility

The Alert component's visibility is controlled via the isVisible prop. Use a state variable in the parent component to manage this. The onVisibleChange callback informs the parent about the user's intent to close the alert (if isClosable is true).

MyComponent.tsx

function ControlledVisibilityAlert() {
  const [showAlert, setShowAlert] = React.useState(false);

  return (
    <View style={{gap: 10}}>
      <CrossBuildButton onPress={() => setShowAlert(!showAlert)}>
        {showAlert ? 'Hide Alert' : 'Show Alert'}
      </CrossBuildButton>
      <Alert
        title="Controlled Visibility"
        description="This alert's visibility is managed by parent state."
        color="primary"
        isVisible={showAlert}
        isClosable // Optional: allow user to close it too
        onVisibleChange={setShowAlert} // Important to update parent state
      />
    </View>
  );
}

Hide Icon Wrapper

If your custom icon already includes spacing, you can use hideIconWrapper to remove the default padding around the icon.

MyComponent.tsx

<Alert
  title="Icon with No Wrapper Padding"
  color="primary"
  icon={<Icon name="settings" size={24} color="white" />} // Icon might have its own padding
  hideIconWrapper
  description="The icon's default wrapper styling is removed."
/>

Props Overview

PROP	TYPE	DEFAULT	DESCRIPTION
`title`	`ReactNode`	-	Main title of the alert.
`description`	`ReactNode`	-	Detailed description text.
`icon`	`React.ReactElement`	-	Custom icon element.
`color`	`AlertColor ('primary' \| ...)`	`'default'`	Semantic color. For 'glass' variant, this primarily influences the choice of default icon; text and default icon colors typically default to theme foreground.
`variant`	`AlertVariant ('solid' \| ... \| 'glass')`	`'solid'`	Visual style.
`radius`	`AlertRadius`	`'md'`	Border radius.
`startContent`	`ReactNode`	-	Content at the start.
`endContent`	`ReactNode`	-	Content at the end.
`isVisible`	`boolean`	`true`	Controls visibility.
`isClosable`	`boolean`	`false`	Show close button.
`hideIcon`	`boolean`	`false`	Hide the icon.
`hideIconWrapper`	`boolean`	`false`	Hide icon's wrapper styling.
`closeButtonProps`	`PressableProps & { icon?: ReactNode }`	-	Props for the close button.
`style`	`StyleProp<ViewStyle>`	-	Styles for the container.
`onClose`	`() => void`	-	Callback when closed.
`onVisibleChange`	`(isVisible: boolean) => void`	-	Callback for visibility change intent.
`glassTint`	`'default' \| 'light' \| 'dark'`	Theme-derived	Tint for the 'glass' variant blur effect.
`glassIntensity`	`number`	50	Intensity (0-100) for the 'glass' variant blur effect.

Styling

Customize the Alert appearance using the style prop for the main container. The Alert.tsx uses a flat StyleSheet for internal elements. For the glass variant, the background is rendered by BlurView from expo-blur, and its appearance is controlled by glassIntensity and glassTint props. The main style prop's backgroundColor will be overridden for the glass variant.

Based on the internal structure, potential styleable parts (if a styles prop were implemented) could be:

base: The main alert container. (Currently targeted by the main style prop).
iconWrapper: The view wrapping the icon.
textContent: The view wrapping title and description.
title: The title text.
description: The description text.
startContentWrapper: Wrapper for start content.
endContentWrapper: Wrapper for end content.
closeButton: The pressable close button.

Styling Note

The provided Alert.tsx component does not explicitly implement a styles prop for slot-based styling like some other components. Customization is primarily through the main style prop and individual props like closeButtonProps. The example below demonstrates how one might style if such a prop existed or by targeting with the main style prop and carefully considering internal structure.

MyComponent.tsx

<Alert
  title="Custom Styled Alert"
  description="This alert has custom slot styling."
  color="warning"
  variant="bordered"
  style={{ marginVertical: 10, elevation: 5 }} // Styles the outermost 'base' container
  styles={{
    base: { shadowColor: '#000', shadowOffset: { width: 0, height: 2 }, shadowOpacity: 0.25, shadowRadius: 3.84 },
    iconWrapper: { backgroundColor: 'rgba(255, 165, 0, 0.1)', borderRadius: 999, padding: 6 },
    title: { color: 'darkorange', fontSize: 18, textTransform: 'uppercase' },
    description: { color: 'orange', fontStyle: 'italic' },
    closeButton: { backgroundColor: 'lightgray', borderRadius: 4, padding: 2 }
  }}
  isClosable
  icon={<Icon name="build" size={20} color="orange" />}
/>

Accessibility

The Alert component includes accessibility features:

The root View has accessibilityRole="alert".
If isClosable is true, the close button has accessibilityRole="button" and accessibilityLabel="Close alert".
Ensure that title and description provide clear and concise information.

Switch Circular Progress