StatusBar

17:06

Description

An immersive status-bar placeholder. Uses the system status bar height to render a placeholder of equal height (in px), pushing page content below the status bar so a custom navigation bar does not overlap it; background sets the area's background color (default transparent). H5 has no system status bar, so the height is always 0.

Compatibility

Platform	Support
App	✅ Supported (fills the status-bar height under a custom navigation bar)
H5	✅ Supported (no system status bar, so the height is always 0)
WeChat Mini Program	✅ Supported

Examples

Basic Usage

Transparent background by default, automatically occupies the system status bar height.

View source

<template>
    <!-- 占位状态栏，与系统状态栏同高 -->
    <ux-status-bar />
    <view class="content">
        <text>状态栏下方内容</text>
    </view>
</template>

<style scoped>
.content {
    height: 60px;
    display: flex;
    align-items: center;
    justify-content: center;
    background-color: #f2f3f5;
}
</style>

Custom Background Color

Set the status bar background color via the background prop.

View source

<template>
    <ux-status-bar background="#2979ff" />
    <view class="content">
        <text class="content-text">状态栏下方内容</text>
    </view>
</template>

<style scoped>
.content {
    height: 60px;
    display: flex;
    align-items: center;
    justify-content: center;
    background-color: #2979ff;
}
.content-text {
    color: #ffffff;
}
</style>

API

Props

Property	Description	Type	Default	Version
customStyle	Custom root element style	string | UTSJSONObject	-	-
customClass	Custom root element style class	string	''	-
background	Background style	string	'transparent'	-

Events

ux-status-bar has no events.

Slots

Slot	Description	Version
default	Custom content inside the status bar (empty by default)	-

Notes

• H5 has no system status bar, so statusBarHeight is always 0 and the component height is 0 (takes no space) — this is expected.
• The height comes from uni.getWindowInfo().statusBarHeight, which is 0 in iOS landscape.
• background defaults to transparent and only reserves space without a color; immersive scenarios usually pass a concrete color matching the page background.
• Content in the default slot does not avoid the status bar automatically; the slot is only for adding custom content within the status-bar area.
• The component has no events.