Skip to content

Commit 492b08e

Browse files
authored
docs: rephrase translucent StatusBar handling on Android for keyboardVerticalOffset (#892)
## 📜 Description Re-phrased note about `translucent` StatusBar. ## 💡 Motivation and Context When I re-read explanation again I realized that it's not very clear how it should work. So I re-phrazed it. Also in this PR I changed width of SVG image, and added missing punctuation signs 🙂 ## 📢 Changelog <!-- High level overview of important changes --> <!-- For example: fixed status bar manipulation; added new types declarations; --> <!-- If your changes don't affect one of platform/language below - then remove this platform/language --> ### Docs - replace SVGs; - rephrase a note about `translucent` StatusBar. ## 🤔 How Has This Been Tested? Tested via preview. ## 📸 Screenshots (if appropriate): <img width="940" alt="image" src="https://github.com/user-attachments/assets/23ca0382-f01f-4cfe-8222-ab8a0df5dcb7" /> ## 📝 Checklist - [x] CI successfully passed - [x] I added new mocks and corresponding unit-tests if library API was changed
1 parent 39e992e commit 492b08e

File tree

4 files changed

+16
-20
lines changed

4 files changed

+16
-20
lines changed

docs/docs/api/components/keyboard-avoiding-view.mdx

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -132,7 +132,7 @@ A boolean prop indicating whether `KeyboardAvoidingView` is enabled or disabled.
132132

133133
### `keyboardVerticalOffset`
134134

135-
This is the distance between the top of the user screen and the react native view This is particularly useful when there are fixed headers, navigation bars, or other UI elements at the top of the screen. Default is `0`.
135+
This is the distance between the top of the user screen and the react native view. This is particularly useful when there are fixed headers, navigation bars, or other UI elements at the top of the screen. Default is `0`.
136136

137137
import KeyboardVerticalOffset from "@site/src/components/KeyboardVerticalOffset";
138138

@@ -169,19 +169,17 @@ Below shown a visual representation of `keyboardVerticalOffset`:
169169

170170
<KeyboardVerticalOffset />
171171

172-
:::warning Translucent `StatusBar`
173-
If you are using translucent `StatusBar` on Android, then `StatusBar` padding gets handled by `react-navigation` automatically and it will include safe-area padding in `useHeaderHeight` (i. e. `StatusBar` height will be included in the returned value and it will match iOS behavior).
172+
:::warning Handling `StatusBar` height on Android with `useHeaderHeight`
173+
On `Android`, how you handle the `StatusBar` height depends on whether the `StatusBar` is **translucent** or **not**:
174174

175-
If you are not using translucent `StatusBar`, then you need to include `StatusBar` height yourself:
175+
- **If the `StatusBar` is translucent**, `react-navigation` **automatically includes the `StatusBar` height** in `useHeaderHeight()`, along with safe-area padding. This behavior aligns with iOS, so you don’t need to manually add the `StatusBar` height.
176+
- **If the StatusBar is not translucent**, `useHeaderHeight()` does **not** include the `StatusBar` height. In this case, you need to add it manually:
176177

177178
```tsx
178179
const headerHeight = useHeaderHeight() + (StatusBar.currentHeight ?? 0);
179180
```
180181

181-
<blockquote>
182-
`StatusBar.currentHeight` is Android-only prop so you can use `?? 0` and don't
183-
write platform-specific code using `Platform.OS` or `Platform.select`.
184-
</blockquote>
182+
Since `StatusBar.currentHeight` is an **Android-only** property, using `?? 0` ensures it doesn’t cause issues on iOS. This approach avoids the need for `Platform.OS` or `Platform.select` checks.
185183

186184
:::
187185

docs/src/components/KeyboardVerticalOffset/kvo-dark.svg

Lines changed: 2 additions & 2 deletions
Loading

docs/src/components/KeyboardVerticalOffset/kvo-light.svg

Lines changed: 2 additions & 2 deletions
Loading

docs/versioned_docs/version-1.16.0/api/components/keyboard-avoiding-view.mdx

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -132,7 +132,7 @@ A boolean prop indicating whether `KeyboardAvoidingView` is enabled or disabled.
132132

133133
### `keyboardVerticalOffset`
134134

135-
This is the distance between the top of the user screen and the react native view This is particularly useful when there are fixed headers, navigation bars, or other UI elements at the top of the screen. Default is `0`.
135+
This is the distance between the top of the user screen and the react native view. This is particularly useful when there are fixed headers, navigation bars, or other UI elements at the top of the screen. Default is `0`.
136136

137137
import KeyboardVerticalOffset from "@site/src/components/KeyboardVerticalOffset";
138138

@@ -169,19 +169,17 @@ Below shown a visual representation of `keyboardVerticalOffset`:
169169

170170
<KeyboardVerticalOffset />
171171

172-
:::warning Translucent `StatusBar`
173-
If you are using translucent `StatusBar` on Android, then `StatusBar` padding gets handled by `react-navigation` automatically and it will include safe-area padding in `useHeaderHeight` (i. e. `StatusBar` height will be included in the returned value and it will match iOS behavior).
172+
:::warning Handling `StatusBar` height on Android with `useHeaderHeight`
173+
On `Android`, how you handle the `StatusBar` height depends on whether the `StatusBar` is **translucent** or **not**:
174174

175-
If you are not using translucent `StatusBar`, then you need to include `StatusBar` height yourself:
175+
- **If the `StatusBar` is translucent**, `react-navigation` **automatically includes the `StatusBar` height** in `useHeaderHeight()`, along with safe-area padding. This behavior aligns with iOS, so you don’t need to manually add the `StatusBar` height.
176+
- **If the StatusBar is not translucent**, `useHeaderHeight()` does **not** include the `StatusBar` height. In this case, you need to add it manually:
176177

177178
```tsx
178179
const headerHeight = useHeaderHeight() + (StatusBar.currentHeight ?? 0);
179180
```
180181

181-
<blockquote>
182-
`StatusBar.currentHeight` is Android-only prop so you can use `?? 0` and don't
183-
write platform-specific code using `Platform.OS` or `Platform.select`.
184-
</blockquote>
182+
Since `StatusBar.currentHeight` is an **Android-only** property, using `?? 0` ensures it doesn’t cause issues on iOS. This approach avoids the need for `Platform.OS` or `Platform.select` checks.
185183

186184
:::
187185

0 commit comments

Comments
 (0)