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-contextopens in a new window 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 - SafeAreaViewopens in a new window props.

Name	Type	Default	Description
disableDefaultProviderProps	boolean | undefined	false	If set to true, the component will not use the DefaultPropsProvider values. If you aren’t using the DefaultPropsProvider, this prop can be ignored.
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	"margin" | "padding" | 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	NativeSyntheticEventHandler<TargetedEvent>		Called when the view loses focus
onFocus	NativeSyntheticEventHandler<TargetedEvent>		Called when the view gains focus
rootTestID	string | undefined		Adds the passed in test ID to the root element of the component.
style	Style<"SafeAreaView">		Style properties with Abyss token mapping
styles	Styles<SafeAreaViewClasses> | undefined		Add custom styles to component by class name with Abyss token mapping
testID	string | undefined		Using this prop will append -abyss and the name of the element class at the end of the testID passed in. If you want to only use string passed in on the root element, use the rootTestID prop instead. Used to locate this view in end-to-end tests.