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 @crossbuildui/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, and faded.

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." />
</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>

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`	`'default'`	Semantic color.
`variant`	`AlertVariant`	`'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.

Styling

Customize the Alert appearance using the style prop for the main container or the styles prop (if available, though not explicitly shown in the provided Alert.tsx for slots) for more granular control. The provided Alert.tsx uses a flat StyleSheet. For slot-based styling, the component would need to expose a styles prop that maps to internal elements.

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