import { SafeAreaView } from '@uhg-abyss/mobile';

Usage

The purpose of SafeAreaView is to render content within the safe area boundaries of a device.

The Abyss SafeAreaView is built on top of the SafeAreaView component provided by the react-native-safe-area-context library. Please install the library in your project to use the Abyss SafeAreaView component. If the library is not installed, the Abyss SafeAreaView will fallback to the React Native SafeAreaView component.

SafeAreaView renders nested content and automatically applies padding to reflect the portion of the view that is not covered by navigation bars, tab bars, toolbars, and other ancestor views. Moreover, and most importantly, Safe Area's paddings reflect the physical limitation of the screen, such as rounded corners or camera notches (i.e. the sensor housing area on iPhone 13).

Edges

You can set the edges to apply the safe area insets to by using the edges prop.

For example if you don't want insets to apply to the top edge because the view does not touch the top of the screen you can use:

<SafeAreaView edges={['bottom', 'left', 'right']}>...</SafeAreaView>

Optionally it can be set to an object { top?: EdgeMode, right?: EdgeMode, bottom?: EdgeMode, left?: EdgeMode } where EdgeMode = 'off' | 'additive' | 'maximum'. Additive is a default mode and is the same as passing and edge in the array: finalPadding = safeArea + padding. Maximum mode will use safe area inset or padding/margin (depends on mode) if safe area is less: finalPadding = max(safeArea, padding). For example if you want a floating UI element that should be at the bottom safe area edge on devices with safe area or 24px from the bottom of the screen on devices without safe area or if safe area is less than 24px:

<SafeAreaView style={{ paddingBottom: 24 }} edges={{ bottom: 'maximum' }}>
  ...
</SafeAreaView>

Example

<View style={{ flex: 1, justifyContent: 'space-between' }}>
  <SafeAreaView
    edges={['top', 'left', 'right']}
    style={{ backgroundColor: '$core.color.brand.100' }}
  >
    <View style={{ padding: '$semantic.spacing.lg' }}>
      <Text textAlign="center" color="$semantic.color.text.body.alt">
        This is a SafeAreaView that avoids the Status Bar
      </Text>
    </View>
  </SafeAreaView>
  <SafeAreaView
    edges={['bottom', 'left', 'right']}
    style={{ backgroundColor: '$core.color.brand.100' }}
  >
    <View style={{ padding: '$semantic.spacing.lg' }}>
      <Text textAlign="center" color="$semantic.color.text.body.alt">
        This is a SafeAreaView that avoids the Home Bar
      </Text>
    </View>
  </SafeAreaView>
</View>

() => {
  const PhoneContainer = styled('View', {
    justifyContent: 'space-between',
    width: '100%',
  });

  const PaddedView = styled('View', {
    paddingHorizontal: '$semantic.spacing.lg',
    backgroundColor: '$core.color.brand.100',
    width: '100%',
    variants: {
      placement: {
        top: {
          paddingTop: 40,
          paddingBottom: '$semantic.spacing.lg',
        },
        bottom: {
          paddingBottom: 28,
          paddingTop: '$semantic.spacing.lg',
        },
      },
    },
  });

  const Label = styled('Text', {
    color: '$semantic.color.text.body.alt',
    fontSize: '$semantic.font-size.body.60',
    textAlign: 'center',
  });

  return (
    <PhoneContainer>
      <PaddedView placement="top">
        <Label>This is a SafeAreaView that avoids the Status Bar</Label>
      </PaddedView>
      <PaddedView placement="bottom">
        <Label>This is a SafeAreaView that avoids the Home Bar</Label>
      </PaddedView>
    </PhoneContainer>
  );
};

SafeAreaView Classes

Class Name	Description
abyss-safe-area-view-root	SafeAreaView root element

SafeAreaView Props

Extends React Native - SafeAreaView props.

Name	Type	Default	Required	Description
edges	Edges | undefined	-	-	Sets the edges to apply the safe area insets to. For example if you don't want insets to apply to the top edge because the view does not touch the top of the screen you can use: <SafeAreaView edges={['right', 'bottom', 'left']} /> You can also specify edge modes: <SafeAreaView edges={{ top: 'maximum', bottom: 'additive' }} /> - 'off' - don't apply insets for the specified edge - 'additive' - (default) add the safe area inset to the existing padding or margin - 'maximum' - use the larger of the existing padding/margin or the safe area inset
hitSlop	number | Insets | null | undefined	-	-	This defines how far a touch event can start away from the view. Typical interface guidelines recommend touch targets that are at least 30 - 40 points/density-independent pixels. If a Touchable view has a height of 20 the touchable height can be extended to 40 with hitSlop={{ top: 10, bottom: 10, left: 0, right: 0 }} NOTE The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.
mode	"padding" | "margin" | undefined	'padding'	-	The mode to use to apply safe area insets. 'padding' will add the insets to the existing padding of the view, while 'margin' will add the insets to the existing margin of the view. Defaults to 'padding'.
onBlur	Abyss.NativeSyntheticEventHandler<TargetedEvent>	-	-	Called when the view loses focus
onFocus	Abyss.NativeSyntheticEventHandler<TargetedEvent>	-	-	Called when the view gains focus
style	Abyss.Style<"SafeAreaView">	-	-	SafeAreaView style properties with Abyss token mapping