Safe Area 여백 값 구하기

모바일 브라우저에서는 상태바나 홈 인디케이터 같은 시스템 UI 때문에 콘텐츠가 가려질 때가 있어요. getSafeAreaInsets 함수는 시스템 UI가 콘텐츠를 가리지 않도록 화면의 안전 영역(Safe Area) 여백 값을 픽셀 단위로 계산해줘요.

특히 iPhone X 이상의 기기나 일부 Android 기기에서는 전체 화면을 사용하는 웹 앱에서 시스템 UI가 콘텐츠를 가리는 문제가 자주 발생해요. 다음과 같이 getSafeAreaInsets를 사용하면 콘텐츠가 안전하게 보이도록 여백을 조절할 수 있어요.

import { getSafeAreaInsets } from "@apps-in-toss/web-framework";

const insets = getSafeAreaInsets();
// 예시 반환값: { top: 44, bottom: 34 }

반환되는 객체는 다음 속성을 포함해요.

• top: 상단 상태바에 가리지 않도록 확보해야 하는 여백이에요.
• bottom: 하단 홈 인디케이터에 가리지 않도록 확보해야 하는 여백이에요.

이 값은 모바일 웹 앱에서 전체 화면(viewport)에 맞춰 UI를 만들 때 자주 사용돼요. 예를 들어, 하단 고정 버튼에 여백을 주거나 상단 헤더가 상태바에 겹치지 않도록 만들 수 있어요.

하단 여백 적용 예시

하단 고정 버튼이 홈 인디케이터에 겹치지 않도록 여백을 주는 예시예요.

import { getSafeAreaInsets } from "@apps-in-toss/web-framework";

const insets = getSafeAreaInsets();

const Button = () => {
  return (
    <div style={{ paddingBottom: `${insets.bottom}px` }}>
      <button>확인</button>
    </div>
  );
};

상단 여백 적용 예시

상단 고정 헤더가 상태바에 겹치지 않도록 여백을 주는 예시예요.

import { getSafeAreaInsets } from "@apps-in-toss/web-framework";

const insets = getSafeAreaInsets();

const Header = () => {
  return (
    <div style={{ paddingTop: `${insets.top}px` }}>
      <h1>제목</h1>
    </div>
  );
};