react-native-audio-browser 0.2.0-next.54 → 0.2.0-next.56

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (271) hide show
  1. package/README.md +32 -19
  2. package/lib/commonjs/CLAUDE.md +7 -2
  3. package/lib/commonjs/features/battery.js +16 -12
  4. package/lib/commonjs/features/battery.js.map +1 -1
  5. package/lib/commonjs/features/browser-config.js +1 -1
  6. package/lib/commonjs/features/browser.js +74 -24
  7. package/lib/commonjs/features/browser.js.map +1 -1
  8. package/lib/commonjs/features/carConnection.js +3 -4
  9. package/lib/commonjs/features/carConnection.js.map +1 -1
  10. package/lib/commonjs/features/equalizer.js +9 -5
  11. package/lib/commonjs/features/equalizer.js.map +1 -1
  12. package/lib/commonjs/features/errors.js +35 -21
  13. package/lib/commonjs/features/errors.js.map +1 -1
  14. package/lib/commonjs/features/favorites.js +15 -13
  15. package/lib/commonjs/features/favorites.js.map +1 -1
  16. package/lib/commonjs/features/gate.js +12 -6
  17. package/lib/commonjs/features/gate.js.map +1 -1
  18. package/lib/commonjs/features/metadata.js +16 -14
  19. package/lib/commonjs/features/metadata.js.map +1 -1
  20. package/lib/commonjs/features/network.js +5 -1
  21. package/lib/commonjs/features/network.js.map +1 -1
  22. package/lib/commonjs/features/nowPlaying.js +28 -14
  23. package/lib/commonjs/features/nowPlaying.js.map +1 -1
  24. package/lib/commonjs/features/output.js +8 -4
  25. package/lib/commonjs/features/output.js.map +1 -1
  26. package/lib/commonjs/features/playback/controls.js +10 -5
  27. package/lib/commonjs/features/playback/controls.js.map +1 -1
  28. package/lib/commonjs/features/playback/playWhenReady.js +6 -5
  29. package/lib/commonjs/features/playback/playWhenReady.js.map +1 -1
  30. package/lib/commonjs/features/playback/playing.js +5 -3
  31. package/lib/commonjs/features/playback/playing.js.map +1 -1
  32. package/lib/commonjs/features/playback/progress.js +11 -5
  33. package/lib/commonjs/features/playback/progress.js.map +1 -1
  34. package/lib/commonjs/features/playback/state.js +3 -3
  35. package/lib/commonjs/features/playback/state.js.map +1 -1
  36. package/lib/commonjs/features/playback/trackPlaybackTime.js +6 -1
  37. package/lib/commonjs/features/playback/trackPlaybackTime.js.map +1 -1
  38. package/lib/commonjs/features/playback/volume.js +6 -5
  39. package/lib/commonjs/features/playback/volume.js.map +1 -1
  40. package/lib/commonjs/features/player/options.js +20 -10
  41. package/lib/commonjs/features/player/options.js.map +1 -1
  42. package/lib/commonjs/features/player/setup.js +34 -38
  43. package/lib/commonjs/features/player/setup.js.map +1 -1
  44. package/lib/commonjs/features/queue/activeTrack.js +0 -1
  45. package/lib/commonjs/features/queue/activeTrack.js.map +1 -1
  46. package/lib/commonjs/features/queue/queue.js +48 -20
  47. package/lib/commonjs/features/queue/queue.js.map +1 -1
  48. package/lib/commonjs/features/queue/repeatMode.js +2 -1
  49. package/lib/commonjs/features/queue/repeatMode.js.map +1 -1
  50. package/lib/commonjs/features/queue/shuffle.js +0 -1
  51. package/lib/commonjs/features/queue/shuffle.js.map +1 -1
  52. package/lib/commonjs/features/remoteControls.js +59 -35
  53. package/lib/commonjs/features/remoteControls.js.map +1 -1
  54. package/lib/commonjs/features/sleepTimer.js +15 -6
  55. package/lib/commonjs/features/sleepTimer.js.map +1 -1
  56. package/lib/commonjs/utils/LazyNativeEmitter.js +6 -9
  57. package/lib/commonjs/utils/LazyNativeEmitter.js.map +1 -1
  58. package/lib/commonjs/utils/NativeUpdatedValue.js +13 -12
  59. package/lib/commonjs/utils/NativeUpdatedValue.js.map +1 -1
  60. package/lib/commonjs/utils/getTrackIdentity.js +6 -4
  61. package/lib/commonjs/utils/getTrackIdentity.js.map +1 -1
  62. package/lib/commonjs/utils/useDebug.js +16 -3
  63. package/lib/commonjs/utils/useDebug.js.map +1 -1
  64. package/lib/commonjs/web/NativeAudioBrowser.js +2 -4
  65. package/lib/commonjs/web/NativeAudioBrowser.js.map +1 -1
  66. package/lib/commonjs/web/browser/parseSearchResponse.js +3 -4
  67. package/lib/commonjs/web/browser/parseSearchResponse.js.map +1 -1
  68. package/lib/commonjs/web/browser/sections.js +1 -1
  69. package/lib/commonjs/web/util/BrowserPathHelper.js +1 -3
  70. package/lib/commonjs/web/util/BrowserPathHelper.js.map +1 -1
  71. package/lib/module/CLAUDE.md +7 -2
  72. package/lib/module/features/battery.js +16 -12
  73. package/lib/module/features/battery.js.map +1 -1
  74. package/lib/module/features/browser-config.js +1 -1
  75. package/lib/module/features/browser.js +74 -24
  76. package/lib/module/features/browser.js.map +1 -1
  77. package/lib/module/features/carConnection.js +3 -4
  78. package/lib/module/features/carConnection.js.map +1 -1
  79. package/lib/module/features/equalizer.js +9 -5
  80. package/lib/module/features/equalizer.js.map +1 -1
  81. package/lib/module/features/errors.js +35 -21
  82. package/lib/module/features/errors.js.map +1 -1
  83. package/lib/module/features/favorites.js +15 -13
  84. package/lib/module/features/favorites.js.map +1 -1
  85. package/lib/module/features/gate.js +12 -6
  86. package/lib/module/features/gate.js.map +1 -1
  87. package/lib/module/features/metadata.js +16 -14
  88. package/lib/module/features/metadata.js.map +1 -1
  89. package/lib/module/features/network.js +5 -1
  90. package/lib/module/features/network.js.map +1 -1
  91. package/lib/module/features/nowPlaying.js +28 -14
  92. package/lib/module/features/nowPlaying.js.map +1 -1
  93. package/lib/module/features/output.js +8 -4
  94. package/lib/module/features/output.js.map +1 -1
  95. package/lib/module/features/playback/controls.js +10 -5
  96. package/lib/module/features/playback/controls.js.map +1 -1
  97. package/lib/module/features/playback/playWhenReady.js +6 -5
  98. package/lib/module/features/playback/playWhenReady.js.map +1 -1
  99. package/lib/module/features/playback/playing.js +5 -3
  100. package/lib/module/features/playback/playing.js.map +1 -1
  101. package/lib/module/features/playback/progress.js +11 -5
  102. package/lib/module/features/playback/progress.js.map +1 -1
  103. package/lib/module/features/playback/state.js +3 -3
  104. package/lib/module/features/playback/state.js.map +1 -1
  105. package/lib/module/features/playback/trackPlaybackTime.js +6 -1
  106. package/lib/module/features/playback/trackPlaybackTime.js.map +1 -1
  107. package/lib/module/features/playback/volume.js +6 -5
  108. package/lib/module/features/playback/volume.js.map +1 -1
  109. package/lib/module/features/player/options.js +20 -10
  110. package/lib/module/features/player/options.js.map +1 -1
  111. package/lib/module/features/player/setup.js +34 -38
  112. package/lib/module/features/player/setup.js.map +1 -1
  113. package/lib/module/features/queue/activeTrack.js +0 -1
  114. package/lib/module/features/queue/activeTrack.js.map +1 -1
  115. package/lib/module/features/queue/queue.js +48 -20
  116. package/lib/module/features/queue/queue.js.map +1 -1
  117. package/lib/module/features/queue/repeatMode.js +2 -1
  118. package/lib/module/features/queue/repeatMode.js.map +1 -1
  119. package/lib/module/features/queue/shuffle.js +0 -1
  120. package/lib/module/features/queue/shuffle.js.map +1 -1
  121. package/lib/module/features/remoteControls.js +59 -35
  122. package/lib/module/features/remoteControls.js.map +1 -1
  123. package/lib/module/features/sleepTimer.js +15 -6
  124. package/lib/module/features/sleepTimer.js.map +1 -1
  125. package/lib/module/utils/LazyNativeEmitter.js +6 -9
  126. package/lib/module/utils/LazyNativeEmitter.js.map +1 -1
  127. package/lib/module/utils/NativeUpdatedValue.js +13 -12
  128. package/lib/module/utils/NativeUpdatedValue.js.map +1 -1
  129. package/lib/module/utils/getTrackIdentity.js +6 -4
  130. package/lib/module/utils/getTrackIdentity.js.map +1 -1
  131. package/lib/module/utils/useDebug.js +16 -3
  132. package/lib/module/utils/useDebug.js.map +1 -1
  133. package/lib/module/web/NativeAudioBrowser.js +2 -4
  134. package/lib/module/web/NativeAudioBrowser.js.map +1 -1
  135. package/lib/module/web/browser/parseSearchResponse.js +3 -4
  136. package/lib/module/web/browser/parseSearchResponse.js.map +1 -1
  137. package/lib/module/web/browser/sections.js +1 -1
  138. package/lib/module/web/util/BrowserPathHelper.js +1 -3
  139. package/lib/module/web/util/BrowserPathHelper.js.map +1 -1
  140. package/lib/typescript/src/features/battery.d.ts +17 -12
  141. package/lib/typescript/src/features/battery.d.ts.map +1 -1
  142. package/lib/typescript/src/features/browser.d.ts +64 -24
  143. package/lib/typescript/src/features/browser.d.ts.map +1 -1
  144. package/lib/typescript/src/features/carConnection.d.ts +3 -4
  145. package/lib/typescript/src/features/carConnection.d.ts.map +1 -1
  146. package/lib/typescript/src/features/equalizer.d.ts +9 -5
  147. package/lib/typescript/src/features/equalizer.d.ts.map +1 -1
  148. package/lib/typescript/src/features/errors.d.ts +37 -22
  149. package/lib/typescript/src/features/errors.d.ts.map +1 -1
  150. package/lib/typescript/src/features/favorites.d.ts +15 -13
  151. package/lib/typescript/src/features/favorites.d.ts.map +1 -1
  152. package/lib/typescript/src/features/gate.d.ts +14 -8
  153. package/lib/typescript/src/features/gate.d.ts.map +1 -1
  154. package/lib/typescript/src/features/metadata.d.ts +37 -17
  155. package/lib/typescript/src/features/metadata.d.ts.map +1 -1
  156. package/lib/typescript/src/features/network.d.ts +5 -1
  157. package/lib/typescript/src/features/network.d.ts.map +1 -1
  158. package/lib/typescript/src/features/nowPlaying.d.ts +28 -14
  159. package/lib/typescript/src/features/nowPlaying.d.ts.map +1 -1
  160. package/lib/typescript/src/features/output.d.ts +8 -4
  161. package/lib/typescript/src/features/output.d.ts.map +1 -1
  162. package/lib/typescript/src/features/playback/controls.d.ts +10 -5
  163. package/lib/typescript/src/features/playback/controls.d.ts.map +1 -1
  164. package/lib/typescript/src/features/playback/playWhenReady.d.ts +6 -5
  165. package/lib/typescript/src/features/playback/playWhenReady.d.ts.map +1 -1
  166. package/lib/typescript/src/features/playback/playing.d.ts +16 -3
  167. package/lib/typescript/src/features/playback/playing.d.ts.map +1 -1
  168. package/lib/typescript/src/features/playback/progress.d.ts +11 -5
  169. package/lib/typescript/src/features/playback/progress.d.ts.map +1 -1
  170. package/lib/typescript/src/features/playback/state.d.ts +8 -3
  171. package/lib/typescript/src/features/playback/state.d.ts.map +1 -1
  172. package/lib/typescript/src/features/playback/trackPlaybackTime.d.ts +9 -2
  173. package/lib/typescript/src/features/playback/trackPlaybackTime.d.ts.map +1 -1
  174. package/lib/typescript/src/features/playback/volume.d.ts +6 -5
  175. package/lib/typescript/src/features/playback/volume.d.ts.map +1 -1
  176. package/lib/typescript/src/features/player/options.d.ts +52 -37
  177. package/lib/typescript/src/features/player/options.d.ts.map +1 -1
  178. package/lib/typescript/src/features/player/setup.d.ts +65 -60
  179. package/lib/typescript/src/features/player/setup.d.ts.map +1 -1
  180. package/lib/typescript/src/features/queue/activeTrack.d.ts +0 -1
  181. package/lib/typescript/src/features/queue/activeTrack.d.ts.map +1 -1
  182. package/lib/typescript/src/features/queue/queue.d.ts +48 -20
  183. package/lib/typescript/src/features/queue/queue.d.ts.map +1 -1
  184. package/lib/typescript/src/features/queue/repeatMode.d.ts +1 -1
  185. package/lib/typescript/src/features/queue/repeatMode.d.ts.map +1 -1
  186. package/lib/typescript/src/features/queue/shuffle.d.ts +0 -1
  187. package/lib/typescript/src/features/queue/shuffle.d.ts.map +1 -1
  188. package/lib/typescript/src/features/remoteControls.d.ts +58 -25
  189. package/lib/typescript/src/features/remoteControls.d.ts.map +1 -1
  190. package/lib/typescript/src/features/sleepTimer.d.ts +15 -7
  191. package/lib/typescript/src/features/sleepTimer.d.ts.map +1 -1
  192. package/lib/typescript/src/types/browser-nodes.d.ts +54 -57
  193. package/lib/typescript/src/types/browser-nodes.d.ts.map +1 -1
  194. package/lib/typescript/src/types/browser.d.ts +181 -144
  195. package/lib/typescript/src/types/browser.d.ts.map +1 -1
  196. package/lib/typescript/src/utils/LazyNativeEmitter.d.ts +6 -9
  197. package/lib/typescript/src/utils/LazyNativeEmitter.d.ts.map +1 -1
  198. package/lib/typescript/src/utils/NativeUpdatedValue.d.ts +13 -12
  199. package/lib/typescript/src/utils/NativeUpdatedValue.d.ts.map +1 -1
  200. package/lib/typescript/src/utils/getTrackIdentity.d.ts +6 -4
  201. package/lib/typescript/src/utils/getTrackIdentity.d.ts.map +1 -1
  202. package/lib/typescript/src/utils/useDebug.d.ts +16 -3
  203. package/lib/typescript/src/utils/useDebug.d.ts.map +1 -1
  204. package/package.json +1 -1
  205. package/src/CLAUDE.md +7 -2
  206. package/src/docs-floors.test.ts +71 -0
  207. package/src/features/battery.ts +17 -13
  208. package/src/features/browser-config.ts +1 -1
  209. package/src/features/browser.ts +65 -24
  210. package/src/features/carConnection.ts +3 -4
  211. package/src/features/equalizer.ts +9 -5
  212. package/src/features/errors.ts +37 -22
  213. package/src/features/favorites.ts +15 -13
  214. package/src/features/gate.ts +14 -8
  215. package/src/features/metadata.ts +37 -17
  216. package/src/features/network.ts +5 -1
  217. package/src/features/nowPlaying.ts +28 -14
  218. package/src/features/output.ts +8 -4
  219. package/src/features/playback/controls.ts +10 -5
  220. package/src/features/playback/playWhenReady.ts +6 -5
  221. package/src/features/playback/playing.ts +16 -3
  222. package/src/features/playback/progress.ts +11 -5
  223. package/src/features/playback/state.ts +8 -3
  224. package/src/features/playback/trackPlaybackTime.ts +9 -2
  225. package/src/features/playback/volume.ts +6 -5
  226. package/src/features/player/options.ts +54 -43
  227. package/src/features/player/setup.ts +67 -61
  228. package/src/features/queue/activeTrack.ts +0 -1
  229. package/src/features/queue/queue.ts +48 -20
  230. package/src/features/queue/repeatMode.ts +1 -1
  231. package/src/features/queue/shuffle.ts +0 -1
  232. package/src/features/remoteControls.ts +59 -35
  233. package/src/features/sleepTimer.ts +15 -7
  234. package/src/types/browser-nodes.ts +54 -57
  235. package/src/types/browser.ts +183 -146
  236. package/src/utils/LazyNativeEmitter.ts +6 -9
  237. package/src/utils/NativeUpdatedValue.ts +13 -12
  238. package/src/utils/getTrackIdentity.ts +6 -4
  239. package/src/utils/useDebug.ts +16 -3
  240. package/src/web/NativeAudioBrowser.ts +2 -4
  241. package/src/web/browser/parseSearchResponse.ts +3 -4
  242. package/src/web/browser/sections.ts +1 -1
  243. package/src/web/util/BrowserPathHelper.ts +1 -3
  244. package/website/guide/android-auto.md +25 -13
  245. package/website/guide/android-certificates.md +199 -120
  246. package/website/guide/artwork.md +93 -48
  247. package/website/guide/audio-output.md +86 -68
  248. package/website/guide/automotive.md +15 -10
  249. package/website/guide/basic-usage.md +5 -2
  250. package/website/guide/battery.md +50 -23
  251. package/website/guide/browser.md +155 -68
  252. package/website/guide/carplay.md +132 -49
  253. package/website/guide/configuration.md +85 -49
  254. package/website/guide/equalizer.md +36 -32
  255. package/website/guide/errors.md +106 -64
  256. package/website/guide/favorites.md +41 -31
  257. package/website/guide/gate.md +24 -10
  258. package/website/guide/getting-started.md +55 -2
  259. package/website/guide/hooks.md +53 -47
  260. package/website/guide/live-streams.md +80 -49
  261. package/website/guide/metadata.md +87 -53
  262. package/website/guide/migrating-from-track-player.md +94 -49
  263. package/website/guide/native-callback-fetch.md +46 -36
  264. package/website/guide/network.md +36 -20
  265. package/website/guide/now-playing.md +72 -44
  266. package/website/guide/playback.md +112 -35
  267. package/website/guide/queue.md +77 -43
  268. package/website/guide/remote-controls.md +87 -29
  269. package/website/guide/search.md +37 -22
  270. package/website/guide/sleep-timer.md +35 -14
  271. package/website/guide/track.md +59 -35
@@ -8,11 +8,13 @@ This guide covers the core idea — the **browse tree** — and the minimal code
8
8
 
9
9
  ## The browse tree
10
10
 
11
- The library models all content as one navigable tree of **Tracks**. A single Track is **browsable**, **playable**, or both, depending on which fields you set:
11
+ The library models all content as one navigable tree of **Tracks**. A Track is **browsable** or **playable**, depending on which field you set:
12
12
 
13
13
  - **Browsable** — has a `path`; navigating into it resolves its children.
14
14
  - **Playable** — has a `src`; the player can stream it.
15
15
 
16
+ Set exactly one. [Track → Browsable or playable](/guide/track#browsable-or-playable) covers a Track that sets both.
17
+
16
18
  Three fields at a glance — each answers a different question about a Track:
17
19
 
18
20
  | Field | Answers | Meaning |
@@ -103,7 +105,7 @@ configureBrowser({
103
105
  })
104
106
  ```
105
107
 
106
- A route value is a [`BrowserSource`](/api/types/browser/#browsersource): the static page object shown above, an **async callback** that returns one (`'/path': async ({ routeParams }) => ({ title, children })`), or an HTTP request config that fetches it from your API — handy for trees too large to declare upfront.
108
+ A route value is a [`BrowserSource`](/api/types/browser/#browsersource): the static page object shown above, an **async callback** that returns one (`'/path': async ({ path, routeParams }) => ({ path, title, children })`), or an HTTP request config that fetches it from your API — handy for trees too large to declare upfront.
107
109
 
108
110
  A page can also group its tracks into titled, styled **sections** (`sections: [{ title, style, children }, …]`) — a flat `children` list like the ones above is shorthand for a single untitled section. See [Browser → How a path resolves](/guide/browser#how-a-path-resolves).
109
111
 
@@ -129,6 +131,7 @@ The player works through a **queue** of Tracks. The Track at the current positio
129
131
  Reactive hooks keep your in-app UI in sync with playback — they re-render automatically as it changes:
130
132
 
131
133
  ```tsx
134
+ import { Button } from 'react-native'
132
135
  import {
133
136
  togglePlayback,
134
137
  usePlayingState,
@@ -7,26 +7,30 @@ description: 'Detect the Android 12+ battery restrictions that block the foregro
7
7
  On Android 12+, if the OS has put your app under battery restrictions, it
8
8
  **blocks the foreground service** the player needs to start audio in the
9
9
  background. So when a Bluetooth device or car head unit tries to resume playback
10
- while your app is killed, nothing happens. This feature detects that block and
11
- lets you prompt the user to fix their battery settings.
10
+ while your app is killed, nothing happens.
11
+
12
+ This feature detects that block and lets you prompt the user to fix their
13
+ battery settings.
12
14
 
13
15
  ::: warning Android only
14
16
  This is an **Android-only** concern (Android 12+ foreground-service limits).
15
17
  On iOS every getter/hook here is inert: `getBatteryWarningPending()` is always
16
18
  `false`, `getBatteryOptimizationStatus()` is always `'unrestricted'`, the events
17
19
  never fire, and `dismissBatteryWarning()` / `openBatterySettings()` are no-ops.
18
- So you can render the banner below unconditionally — it simply never shows on iOS.
19
- :::
20
20
 
21
- The UI snippet imports `View` / `Text` / `Button` from `react-native`; everything
22
- else is from `react-native-audio-browser`.
21
+ So you can render the banner below unconditionally: it never shows on iOS.
22
+ :::
23
23
 
24
24
  ## The warning banner
25
25
 
26
- A warning becomes **pending** when a background resume is actually blocked. Show
27
- a banner only while `pending` is true, offering to open settings or dismiss.
28
- [`useBatteryWarning()`](/api/features/battery/#usebatterywarning) bundles
29
- everything you need:
26
+ A warning becomes **pending** when a background resume is actually blocked. The
27
+ block happens while your app is killed, so the library saves the warning and you
28
+ see it the next time the app opens. It stays pending across launches until it
29
+ clears.
30
+
31
+ Show a banner only while `pending` is true, offering to open settings or
32
+ dismiss. [`useBatteryWarning()`](/api/features/battery/#usebatterywarning)
33
+ bundles everything you need:
30
34
 
31
35
  ```tsx
32
36
  import { View, Text, Button } from 'react-native'
@@ -47,17 +51,42 @@ function BatteryWarningBanner() {
47
51
  ```
48
52
 
49
53
  - `openSettings` ([`openBatterySettings`](/api/features/battery/#openbatterysettings))
50
- opens this app's system battery settings. When the user returns having set the
51
- app to unrestricted, the warning clears itself.
54
+ depends on the status. When it is `'optimized'`, it asks the system for the
55
+ dialog that lets the user exempt the app from battery optimization in one tap.
56
+ This works only if your app declares the permission below.
57
+
58
+ With any other status, `'restricted'` included, it opens the app's App info
59
+ page, and the user changes the battery setting from there. When the user
60
+ returns having set the app to unrestricted, the warning clears itself.
61
+
52
62
  - `dismiss` ([`dismissBatteryWarning`](/api/features/battery/#dismissbatterywarning))
53
63
  hides the warning without changing settings.
54
64
 
65
+ ::: warning The one-tap dialog needs a permission
66
+ The library doesn't declare `REQUEST_IGNORE_BATTERY_OPTIMIZATIONS`. Without it,
67
+ Android drops the dialog request in the `'optimized'` state: nothing appears,
68
+ and the status stays `'optimized'`. The library doesn't detect this or fall
69
+ back to another settings page.
70
+
71
+ To get the dialog, declare the permission in your app:
72
+
73
+ ```xml
74
+ <!-- android/app/src/main/AndroidManifest.xml -->
75
+ <uses-permission
76
+ android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
77
+ ```
78
+
79
+ Google Play restricts which apps may declare this permission. Check its policy
80
+ before you add it. If you can't declare it, send users in the `'optimized'`
81
+ state to the system battery settings some other way.
82
+ :::
83
+
55
84
  ## When the warning clears
56
85
 
57
86
  `pending` goes back to `false` when any of these happens — you don't clear it
58
87
  manually:
59
88
 
60
- - the user calls `dismiss`, or
89
+ - your app calls `dismiss` (for example, when the user taps Dismiss), or
61
90
  - the battery status becomes `'unrestricted'` (e.g. they fixed it in settings).
62
91
 
63
92
  ## Battery optimization status
@@ -103,13 +132,11 @@ two actions.
103
132
 
104
133
  ## API summary
105
134
 
106
- | API | Purpose |
107
- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------- |
108
- | `useBatteryWarning()` | Everything for a banner: `{ pending, status, dismiss, openSettings }`. |
109
- | `getBatteryWarningPending()` / `useBatteryWarningPending()` | Is a warning pending? (Android; `false` on iOS) |
110
- | `getBatteryOptimizationStatus()` / `useBatteryOptimizationStatus()` | Current status (Android; `'unrestricted'` on iOS) |
111
- | `onBatteryWarningPendingChanged` / `onBatteryOptimizationStatusChanged` | Subscribe outside React. |
112
- | `openBatterySettings()` | Open the app's system battery settings (Android). |
113
- | `dismissBatteryWarning()` | Dismiss the warning without changing settings (Android). |
114
-
115
- All are **Android-only** — inert (`false` / `'unrestricted'` / no-op) on iOS.
135
+ | API | Purpose |
136
+ | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
137
+ | `useBatteryWarning()` | Everything for a banner: `{ pending, status, dismiss, openSettings }`. |
138
+ | `getBatteryWarningPending()` / `useBatteryWarningPending()` | Is a warning pending? (Android; `false` on iOS) |
139
+ | `getBatteryOptimizationStatus()` / `useBatteryOptimizationStatus()` | Current status (Android; `'unrestricted'` on iOS) |
140
+ | `onBatteryWarningPendingChanged` / `onBatteryOptimizationStatusChanged` | Subscribe outside React. |
141
+ | `openBatterySettings()` | Prompt the user to lift the restriction (Android; see above for the permission the `'optimized'` dialog needs). |
142
+ | `dismissBatteryWarning()` | Dismiss the warning without changing settings (Android). |
@@ -4,13 +4,15 @@ description: 'The reference for configureBrowser: every source shape (static, ca
4
4
 
5
5
  # Browser
6
6
 
7
- The **Browser** is the subsystem that turns one declarative description of your content into a navigable tree — the same tree that powers your in-app browse UI, CarPlay, and Android Auto. You describe it once with **`configureBrowser`**; the library resolves paths, fetches children, transforms requests, and renders the native surfaces for you.
7
+ The **Browser** is the subsystem that turns one declarative description of your content into a navigable tree — the same tree that powers your in-app browse UI, CarPlay, and Android Auto.
8
+
9
+ You describe it once with **`configureBrowser`**; the library resolves paths, fetches children, transforms requests, and renders the native surfaces for you.
8
10
 
9
11
  [Basic Usage](/guide/basic-usage) introduces the browse tree. This guide is the reference for _configuring_ it: every source shape, every routing pattern, and every option on [`BrowserConfiguration`](/api/types/browser/#browserconfiguration).
10
12
 
11
13
  ## A complete example
12
14
 
13
- Here is a full, runnable configuration — call `setupPlayer` once, then `configureBrowser` once. It has two tabs, one **static** route, and one **callback** route. Paste it, swap in your own content, and you have a working browse tree on phone, CarPlay, and Android Auto.
15
+ Here is a full, runnable configuration — call `setupPlayer` once, then `configureBrowser` once. It has two tabs, two **static** routes, and one **callback** route. Paste it, swap in your own content, and you have a working browse tree on phone, CarPlay, and Android Auto.
14
16
 
15
17
  ```ts
16
18
  import { setupPlayer, configureBrowser } from 'react-native-audio-browser'
@@ -38,6 +40,13 @@ configureBrowser({
38
40
  '/browse/jazz': async () => {
39
41
  const stations = await fetchJazzStations() // your code
40
42
  return { path: '/browse/jazz', title: 'Jazz', children: stations }
43
+ },
44
+ '/favorites': {
45
+ path: '/favorites',
46
+ title: 'Favorites',
47
+ children: [
48
+ { title: 'Smooth Floret FM', src: 'https://example.com/floret.mp3' }
49
+ ]
41
50
  }
42
51
  }
43
52
  })
@@ -70,13 +79,22 @@ A **page** is a [`ResolvedTrack`](/api/types/browser-nodes/#resolvedtrack): it r
70
79
  path: '/home',
71
80
  title: 'Home',
72
81
  sections: [
73
- { title: 'Popular', style: { display: 'grid', gridWrap: false }, path: '/popular', children: [...] },
82
+ {
83
+ title: 'Popular',
84
+ style: { display: 'grid', gridWrap: false },
85
+ path: '/popular',
86
+ children: [...]
87
+ },
74
88
  { title: 'All stations', children: [...] }
75
89
  ]
76
90
  }
77
91
  ```
78
92
 
79
- A Section is `{ title?, style?, path?, children }`: `title` renders as a header above its tracks, `style` is a declaration block whose `display` picks the children's layout (`'list'` rows — the default — or `'grid'` artwork tiles; `gridWrap: false` keeps the grid to a single line), and `path` is the navigation target for the section's "view all" affordance. See [Presentation](#presentation) for how each surface renders the declarations.
93
+ A Section is `{ title?, style?, path?, children }`. `title` renders as a header above its tracks. `style` is a declaration block whose `display` picks the children's layout: `'list'` rows (the default) or `'grid'` artwork tiles, with `gridWrap: false` keeping the grid to a single line.
94
+
95
+ `path` is the navigation target for the section's "view all" affordance.
96
+
97
+ See [Presentation](#presentation) for how each surface renders the declarations.
80
98
 
81
99
  A flat page doesn't have to spell that out: authoring a plain `children: Track[]` — as most examples in this guide do — is sugar for one untitled section. Resolved output always carries `sections`; `children` is never populated on a resolved page.
82
100
 
@@ -84,7 +102,7 @@ So configuring the Browser is really three decisions, covered in turn below: **w
84
102
 
85
103
  ## Source shapes
86
104
 
87
- Wherever the Browser needs content — a route, the `tabs`, `search` — you supply a **source**, and a source is always one of three shapes. Learn these once; they apply everywhere.
105
+ Wherever the Browser needs content — a route, the `tabs`, `search` — you supply a **source**. A route's source is one of three shapes: static data, a callback, or an HTTP endpoint.
88
106
 
89
107
  ### 1. Static data
90
108
 
@@ -115,7 +133,7 @@ A function `({ path, routeParams }) => ResolvedTrack` (sync or async). Resolve c
115
133
  configureBrowser({
116
134
  routes: {
117
135
  '/albums/{id}': async ({ routeParams }) => {
118
- const album = await fetchAlbum(routeParams.id) // your code
136
+ const album = await fetchAlbum(routeParams?.id) // your code
119
137
  return {
120
138
  path: `/albums/${album.id}`,
121
139
  title: album.name,
@@ -146,8 +164,8 @@ configureBrowser({
146
164
  On an HTTP route, the _navigated_ path is used as the request path — a static `path` field is ignored for this. To remap (e.g. send `/favorites` to `/favorites/v2`), use a [transform](#transforms-per-request), which also receives `routeParams`.
147
165
  :::
148
166
 
149
- ::: tip Same three shapes, everywhere
150
- `tabs` and `search` accept these same shapes. Once you know static vs. callback vs. HTTP, you know how to configure every part of the Browser. For example, `search` as a callback is just another source returning tracks:
167
+ ::: tip Tabs and search
168
+ `tabs` accepts the same three shapes, but its static form and its callback give a `Track[]`, not a page. `search` accepts a callback or an HTTP endpoint, with no static form. Its callback receives the search params and returns a `Track[]`:
151
169
 
152
170
  ```ts
153
171
  configureBrowser({
@@ -172,12 +190,14 @@ configureBrowser({
172
190
  })
173
191
  ```
174
192
 
175
- ::: warning Maximum 4 tabs
176
- CarPlay and Android Auto cap the tab bar, so `tabs` is limited to **4**. More than four triggers a runtime warning and the extras are dropped.
193
+ ::: warning Car surfaces show only the first few tabs
194
+ Android Auto shows the first **4** tabs. CarPlay shows as many as `CPTabBarTemplate.maximumTabCount` allows. Only those surfaces hide the extra tabs: `getTabs` and `useTabs` return every tab. A debug build warns when a static `tabs` array has more tabs than Android Auto shows.
177
195
  :::
178
196
 
179
197
  ::: tip A tab's path stays a tab
180
- Link freely to a tab's own path — a "view all" section header on one tab pointing at another tab's route, say. On CarPlay (iOS 17+) that **switches to the tab** instead of pushing a second copy of it onto the current tab's stack, so the user lands where the tab bar already shows that content, with no Back button to a page they never came from. Elsewhere — earlier iOS, Android Auto, your app UI — it navigates as usual.
198
+ Link freely to a tab's own path — a "view all" section header on one tab pointing at another tab's route, say. On CarPlay (iOS 17+) that **switches to the tab** instead of pushing a second copy of it onto the current tab's stack.
199
+
200
+ The user lands where the tab bar already shows that content, with no Back button to a page they never came from. Elsewhere — earlier iOS, Android Auto, your app UI — it navigates as usual.
181
201
  :::
182
202
 
183
203
  Like any source, `tabs` can also be a **callback** — useful when the tabs themselves depend on runtime state, such as a debug build or the current user:
@@ -198,7 +218,8 @@ configureBrowser({
198
218
 
199
219
  ```ts
200
220
  configureBrowser({
201
- path: '/home', // where browse opens; defaults to the first tab's path (or '/')
221
+ // where browse opens; defaults to the first tab's path (or '/')
222
+ path: '/home',
202
223
  tabs: [
203
224
  /* … */
204
225
  ]
@@ -218,7 +239,9 @@ Patterns match on **exact segment count** first — `/artists` does _not_ match
218
239
  | `/favorites` | exactly `/favorites` | — |
219
240
  | `/albums/{id}` | `/albums/floret`, `/albums/42` | `routeParams.id` |
220
241
  | `/artists/*` | any single segment at that position (`/artists/anything`) | — |
221
- | `/files/**` | `/files/...` at any depth below | `routeParams.tail` |
242
+ | `/files/**` | `/files` itself, and `/files/...` at any depth below | `routeParams.tail` |
243
+
244
+ On `/files` itself, `routeParams.tail` is `undefined`.
222
245
 
223
246
  When several patterns match, **most specific wins**: constant > `{param}` > `*` > `**`. So `/albums/new` and `/albums/{id}` can coexist — `/albums/new` takes the literal route.
224
247
 
@@ -228,15 +251,17 @@ configureBrowser({
228
251
  // literal — checked first
229
252
  '/albums/new': newReleasesPage,
230
253
  // {id} otherwise
231
- '/albums/{id}': ({ routeParams }) => fetchAlbum(routeParams.id),
254
+ '/albums/{id}': ({ routeParams }) => fetchAlbum(routeParams?.id),
232
255
  // deep file paths
233
- '/files/**': ({ routeParams }) => listFiles(routeParams.tail)
256
+ '/files/**': ({ routeParams }) => listFiles(routeParams?.tail)
234
257
  }
235
258
  })
236
259
  ```
237
260
 
238
261
  ::: warning The bare `'*'` key is the _default_, not a wildcard segment
239
- A single-segment wildcard only works as a `*` **segment inside a longer pattern** (e.g. `/artists/*`). The bare top-level key `'*'` is different: it's the **custom default** — the source used for any path no other route matches (and only needed if you want to override the built-in HTTP default).
262
+ A single-segment wildcard only works as a `*` **segment inside a longer pattern** (e.g. `/artists/*`).
263
+
264
+ The bare top-level key `'*'` is different: it's the **custom default** — the source used for any path no other route matches (and only needed if you want to override the built-in HTTP default).
240
265
 
241
266
  ```ts
242
267
  routes: {
@@ -256,20 +281,19 @@ A callback (or transform) receives the captured params in `routeParams`:
256
281
  ```ts
257
282
  '/stations/{country}/{city}': async ({ routeParams }) => {
258
283
  // /stations/nl/amsterdam → { country: 'nl', city: 'amsterdam' }
259
- return fetchStations(routeParams.country, routeParams.city)
284
+ return fetchStations(routeParams?.country, routeParams?.city)
260
285
  }
261
286
  ```
262
287
 
263
288
  ### Per-route overrides
264
289
 
265
- A route value can be a bare source (the common case) **or** a [`RouteConfig`](/api/types/browser/#routeconfig) object that overrides request behavior for just that subtree — its `browse` source, plus its own `media` and `artwork` config:
290
+ A route value can be a bare source (the common case) **or** a [`RouteConfig`](/api/types/browser/#routeconfig) object that overrides request behavior for just that subtree — its `browse` source, plus its own `artwork` config. The web ignores a route's `artwork` and uses the top-level `artwork` config.
266
291
 
267
292
  ```ts
268
293
  configureBrowser({
269
294
  routes: {
270
295
  '/premium/**': {
271
- browse: { baseUrl: 'https://api.example.com/premium' },
272
- media: { baseUrl: 'https://premium-audio.cdn.example.com' },
296
+ browse: { baseUrl: 'https://premium-api.example.com' },
273
297
  artwork: { baseUrl: 'https://premium-images.cdn.example.com' }
274
298
  }
275
299
  }
@@ -294,26 +318,29 @@ configureBrowser({
294
318
  request: { baseUrl: 'https://api.example.com', headers: { 'x-app': 'demo' } },
295
319
  browse: { query: { client: 'audio-browser', hl: 'en' } },
296
320
  routes: {
297
- // inherits baseUrl + header + query; navigated path is the request path
298
- '/browse/jazz': {}
321
+ // adds genre=jazz on top of the request and browse layers;
322
+ // the navigated path is the request path
323
+ '/browse/jazz': { query: { genre: 'jazz' } }
299
324
  }
300
325
  })
301
326
  ```
302
327
 
328
+ A path that needs nothing extra needs no route at all: an unmatched path is fetched through `request` and `browse`. An empty route object (`{}`) is not a request config: it is read as a static page with no `path` or `title`. On iOS and Android `configureBrowser` throws on it, on web it renders a blank page, and a debug build warns about it.
329
+
303
330
  ### RequestConfig fields
304
331
 
305
- Every request layer is a [`RequestConfig`](/api/types/browser/#requestconfig) — set only the fields you need; they merge (query params merge additively, scalars override):
332
+ Every request layer is a [`RequestConfig`](/api/types/browser/#requestconfig) — set only the fields you need. Headers and query params merge key by key; other fields override:
306
333
 
307
- | Field | Purpose |
308
- | ---------------------- | ----------------------------------------------------------------------------------- |
309
- | `baseUrl` / `path` | Where to send the request (note: `path` doesn't override the navigated browse path) |
310
- | `method` | `GET` (default), `POST`, … |
311
- | `headers` | HTTP headers |
312
- | `query` | Query parameters (merged additively) |
313
- | `body` / `contentType` | Request body, e.g. for `POST` |
314
- | `userAgent` | `User-Agent` override |
334
+ | Field | Purpose |
335
+ | ---------------------- | ------------------------------------------------------------------------------------ |
336
+ | `baseUrl` / `path` | Where to send the request (note: `path` doesn't override the navigated browse path) |
337
+ | `method` | `GET` (default), `POST`, … |
338
+ | `headers` | HTTP headers (merged key by key) |
339
+ | `query` | Query parameters (merged key by key) |
340
+ | `body` / `contentType` | Request body, sent for `POST`, `PUT` and `PATCH` (and `DELETE` when set); not on web |
341
+ | `userAgent` | `User-Agent` override (a `User-Agent` in `headers` wins on iOS); ignored on web |
315
342
 
316
- ### Transforms — per request
343
+ ### Transforms: per request
317
344
 
318
345
  When a layer needs to change _per request_ (read the captured `routeParams`, switch a `GET` to a `POST`, remap the path), add a `transform` (async) or `transformSync`. It receives the merged request and returns the final one:
319
346
 
@@ -339,9 +366,11 @@ configureBrowser({
339
366
  })
340
367
  ```
341
368
 
342
- ### Resolvers — values that change rarely
369
+ ### Resolvers: values that change rarely
370
+
371
+ When the _whole_ config depends on runtime state — a domain that varies by environment, a locale, an auth host — make the layer a **resolver**: a thunk returning the config.
343
372
 
344
- When the _whole_ config depends on runtime state — a domain that varies by environment, a locale, an auth host — make the layer a **resolver**: a thunk returning the config. It runs **once per content generation** and is cached until you call [`invalidateAllContent`](#updating-the-configuration), so it's the cheap place to read values that change rarely:
373
+ It runs **once per content generation** and is cached until you call [`invalidateAllContent`](#updating-the-configuration), so it's the cheap place to read values that change rarely:
345
374
 
346
375
  ```ts
347
376
  configureBrowser({
@@ -381,12 +410,15 @@ configureBrowser({
381
410
 
382
411
  With `imageQueryParams`, CarPlay and Android Auto's requested size is injected automatically (`?w=200&h=200`) so each surface gets right-sized art. For full control, an `artwork.transform` receives that size as an [`ImageContext`](/api/types/browser/#imagecontext).
383
412
 
384
- **Now-playing art** can differ from browse-row art — set `nowPlayingArtwork` for the lock screen / car now-playing surface only. It uniquely supports an `{id}` template filled from the active track's `id`:
413
+ **Now-playing art** can differ from browse-row art — set `nowPlayingArtwork` for the lock screen / car now-playing surface only. Like `artwork`, it can use an `{id}` template filled from the active track's `id`:
385
414
 
386
415
  ```ts
416
+ // {id} templating (in any artwork config) is native-only:
417
+ // the web implementation does not apply it
387
418
  configureBrowser({
388
- nowPlayingArtwork: { path: '/artwork/{id}' } // {id} → the active track's id
389
- }) // {id} templating is native-only — not applied by the web implementation
419
+ // {id} → the active track's id
420
+ nowPlayingArtwork: { path: '/artwork/{id}' }
421
+ })
390
422
  ```
391
423
 
392
424
  See [Now Playing](/guide/now-playing) for the metadata side of the now-playing surface.
@@ -395,11 +427,19 @@ See [Now Playing](/guide/now-playing) for the metadata side of the now-playing s
395
427
 
396
428
  Two options control what happens when a playable Track is tapped.
397
429
 
398
- **`singleTrack`** — by default, tapping a track queues **its section** and starts there, so next/previous walk the list the user tapped in. The scope is the page's declared structure: the tapped [Section](#how-a-path-resolves)'s `children`, identical on every surface (a page authored with plain `children` is one untitled section). Rendering may truncate what a section _shows_ — a CarPlay single-line grid fits only so many tiles — but never what _plays_. A page aggregating several sections never leaks next/previous across them. Set `singleTrack: true` to play only the tapped track. If the track has meanwhile disappeared from its section (a stale resume, say), the library plays it as a single track rather than guessing a queue from the changed list.
430
+ **`singleTrack`** — by default, tapping a track queues **its section** and starts there, so next/previous walk the list the user tapped in.
431
+
432
+ The scope is the page's declared structure: the tapped [Section](#how-a-path-resolves)'s `children`, identical on every surface (a page authored with plain `children` is one untitled section). Rendering may truncate what a section _shows_ — a CarPlay single-line grid fits only so many tiles — but never what _plays_.
399
433
 
400
- Section scoping knows _where_ the tap happened, not just on what. Each playable row's path carries the track's identity (`id`, falling back to `src`) and the row's position on the page. So the same track can safely appear in several places on one page: a tap queues the section it happened in, and when a playlist holds the same track twice, next/previous continue from the tapped copy.
434
+ A page aggregating several sections never leaks next/previous across them. Set `singleTrack: true` to play only the tapped track. If the track has meanwhile disappeared from its section (a stale resume, say), the library plays it as a single track rather than guessing a queue from the changed list.
401
435
 
402
- The position is only a tie-breaker. If the page has changed by the time the queue is expanded (a stale resume, say), the first row matching the identity wins instead — a stale position can pick a different copy of the tapped track, never a different track. And tapping a row that's already in the current queue from the same page skips in place rather than requeueing the section.
436
+ Section scoping knows _where_ the tap happened, not just on what. Each playable row's path carries the track's identity (`id`, falling back to `src`) and the row's position on the page.
437
+
438
+ So the same track can safely appear in several places on one page: a tap queues the section it happened in, and when a playlist holds the same track twice, next/previous continue from the tapped copy.
439
+
440
+ The position is only a tie-breaker. If the page has changed by the time the queue is expanded (a stale resume, say), the first row matching the identity wins instead — a stale position can pick a different copy of the tapped track, never a different track.
441
+
442
+ Tapping a row that's already in the current queue from the same page skips in place rather than requeueing the section.
403
443
 
404
444
  **`handleTrackLoad`** — intercept loading entirely. When set, tapping a track calls _your_ handler **instead of** the library auto-playing, and native waits for your promise to resolve before continuing. The two branches differ:
405
445
 
@@ -420,7 +460,9 @@ configureBrowser({
420
460
  })
421
461
  ```
422
462
 
423
- In the video branch, returning without calling the player tells the library "handled — leave audio alone." In the audio branch you take over, so you must explicitly `setQueue` + `play` — both are fire-and-forget calls returning `void`, so there's nothing to await _on them_. The handler itself is a different story: native **awaits the promise your handler returns**, so anything you `await` inside — an auth check, a fetch — delays the tap being treated as handled. Keep slow work out of the handler, or kick it off without awaiting it. (`setQueue`/`play` are covered in [Basic Usage](/guide/basic-usage).)
463
+ In the video branch, returning without calling the player tells the library the tap is handled and audio stays as it is. In the audio branch, call [`setQueue` and `play`](/guide/basic-usage) yourself. Both return `void`, so there is nothing to await on them.
464
+
465
+ Native **awaits the promise your handler returns**. Anything you `await` inside, such as an auth check or a fetch, delays the tap being treated as handled. Keep slow work out of the handler, or start it without awaiting it.
424
466
 
425
467
  ## Reading and driving browse state
426
468
 
@@ -473,7 +515,9 @@ The tree isn't static — content changes, languages switch, environments move.
473
515
  | Everything is stale (locale, domain, auth changed) | `invalidateAllContent()` |
474
516
  | The config _shape_ itself changed | `configureBrowser(newConfig)` |
475
517
 
476
- `notifyContentChanged(path)` refreshes a single path in place — external controllers re-fetch just that page. `invalidateAllContent()` clears every cache and re-resolves all visible surfaces (and re-runs your [resolvers](#resolvers-values-that-change-rarely)) — this is what you call after a language or domain switch. `configureBrowser` replaces everything wholesale.
518
+ `notifyContentChanged(path)` refreshes a single path in place — external controllers re-fetch just that page. `invalidateAllContent()` clears every cache and re-resolves all visible surfaces (and re-runs your [resolvers](#resolvers-values-that-change-rarely)) — this is what you call after a language or domain switch.
519
+
520
+ `configureBrowser` replaces everything wholesale and re-runs initial navigation: the in-app browser opens `path` (or the first tab) again. On web it opens the first tab only when `tabs` is an array, and `/` otherwise. CarPlay and Android Auto keep their place; if the tabs changed, CarPlay rebuilds its tab bar once the user is back at the root.
477
521
 
478
522
  ```ts
479
523
  // language changed → resolvers read the new locale on the next resolve
@@ -506,37 +550,56 @@ configureBrowser({
506
550
  })
507
551
  ```
508
552
 
509
- The `code` values: `content-not-found`, `network-error`, `http-error`, `callback-error`, `empty-content`, `timeout`, `unknown-error`. Your formatter drives both the car dialogs and the [`useFormattedNavigationError`](/api/features/errors/#useformattednavigationerror) hook in your app.
553
+ For the `code` values, see [Navigation errors](/guide/errors#navigation-errors). Your formatter drives both the car dialogs and the [`useFormattedNavigationError`](/api/features/errors/#useformattednavigationerror) hook in your app.
510
554
 
511
555
  ## Presentation
512
556
 
513
557
  Presentation lives in `style` blocks, separate from content, plus a few Track fields and config options. Each surface applies the style properties it supports and ignores the rest — an unsupported property is a no-op, never an error.
514
558
 
515
- | Field | On | Effect | Platform |
516
- | ------------------------------------------------ | ------------------------ | --------------------------------------------------------------------------------- | ------------------- |
517
- | `title` | a section | header above its tracks | all |
518
- | `style: { display: 'grid' }` | a section | wrapping artwork-tile grid | all\* |
519
- | `style: { display: 'grid', gridWrap: false }` | a section | a single line of artwork tiles | all\* |
520
- | `path` | a section | "view all" target — a tappable header on CarPlay, an appended row on Android Auto | all |
521
- | `style` (same block) | a page | declaration for the whole page — a section overrides it for its own children | all |
522
- | `style: { display: 'grid' }` | a browsable track | the layout of the page it opens — Android Auto reads it from the parent item | Android Auto / AAOS |
523
- | `style: { artworkRendering: 'stencil' }` | a track / section / page | tint monochrome artwork to the surface appearance | CarPlay |
524
- | `style: { imageShape: 'circular' }` | a track / section / page | crop `'image'` and `'condensed'` tile artwork circular (people) | CarPlay (iOS 26+) |
525
- | `style: { accessorySymbol: 'lock.fill' }` | a track / section / page | SF Symbol accessory on rows and on `'image'` / `'condensed'` tiles | CarPlay |
526
- | `style: { gridTile: 'card' }` | a section / page | the grid's tile kind: `'plain'` (default), `'image'`, `'card'`, or `'condensed'` | CarPlay (iOS 26+) |
527
- | `style: { cardTint: '#1e3a8a' }` (+ `cardImage`) | a track / section / page | card color and image mode (`'background'` fills the card full-height) | CarPlay (iOS 26+) |
528
- | `disabled: true` | a track | unavailable: never plays; grayed where drawable, hidden elsewhere | all |
529
- | `artwork: 'sf:heart.fill'` | any item | SF Symbol icon (supports `?bg=…&fg=…`) | iOS |
530
- | `live: true` | a track | live indicator | iOS |
531
- | `carPlaySiriListButton: 'top' \| 'bottom'` | a page | place the Siri cell on the page | iOS |
532
- | `albumPath` + `resolveAlbumPath` | track + config | make the now-playing album line tappable | CarPlay |
559
+ | Field | On | Effect | Platform |
560
+ | ------------------------------------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
561
+ | `title` | a section | header above its tracks | all |
562
+ | `style: { display: 'grid' }` | a section | wrapping artwork-tile grid | all\* |
563
+ | `style: { display: 'grid', gridWrap: false }` | a section | a single line of artwork tiles | all\* |
564
+ | `path` | a section | "view all" target: a tappable row on a CarPlay grid (none on a list); an appended `viewMoreTitle` row on Android Auto | all |
565
+ | `style` (same block) | a page | declaration for the whole page — a section overrides it for its own children | all |
566
+ | `style: { display: 'grid' }` | a browsable track | the layout of the page it opens — Android Auto reads it from the parent item | Android Auto / AAOS |
567
+ | `style: { artworkRendering: 'stencil' }` | a track / section / page | tint monochrome artwork to the surface appearance | CarPlay |
568
+ | `style: { imageShape: 'circular' }` | a track / section / page | crop `'image'` and `'condensed'` tile artwork circular (people) | CarPlay (iOS 26+) |
569
+ | `style: { accessorySymbol: 'lock.fill' }` | a track / section / page | SF Symbol accessory on rows and on `'image'` / `'condensed'` tiles | CarPlay |
570
+ | `style: { gridTile: 'card' }` | a section / page | the grid's tile kind: `'plain'` (default), `'image'`, `'card'`, or `'condensed'` | CarPlay (iOS 26+) |
571
+ | `style: { cardTint: '#1e3a8a' }` (+ `cardImage`) | a track / section / page | card color and image mode (`'background'` fills the card full-height) | CarPlay (iOS 26+) |
572
+ | `disabled: true` | a track | unavailable: taps, voice selection, queue expansion and resume refuse it, but a `setQueue` list is not filtered and plays it when reached; grayed where drawable, hidden elsewhere | all |
573
+ | `artwork: 'sf:heart.fill'` | any item | SF Symbol icon (supports `?bg=…&fg=…`) | iOS |
574
+ | `live: true` | a track | live indicator | iOS |
575
+ | `carPlaySiriListButton: 'top' \| 'bottom'` | a page | place the Siri cell on the page | iOS |
576
+ | `albumPath` or `resolveAlbumPath` | track or config | make the now-playing album line tappable | CarPlay |
533
577
 
534
578
  ::: info Caveats from the table
535
- **`albumPath` requires `album`** — CarPlay renders the tappable line from the album metadata, so without an `album` there is no line to tap. **\*Layouts render each platform's nearest supported form** — a single-line grid (`gridWrap: false`) on CarPlay shows the tiles that fit on one line (seven on a wide screen, or two condensed cells) and truncates the rest; a wrapping grid takes as many lines as it needs on iOS 26+ and renders as a list before that. Android Auto's grid always wraps, so it shows more, never less. No car surface scrolls horizontally; an app UI typically renders `gridWrap: false` as a horizontal scroller. Truncation is visual only: tapping a tile queues the whole section (see [Playback behavior](#playback-behavior)). Item properties like `artworkRendering`, `imageShape`, and `accessorySymbol` are inherited — `track ?? section ?? page`, per property — so a section-wide value can be overridden per item; `accessorySymbol: 'none'` is the per-item escape from an inherited symbol, and where the accessory draws is the platform's choice per surface (trailing on list rows and condensed tiles, leading the title on image tiles). On an iOS 26 grid, which tile draws what is `gridTile`'s choice: `'plain'` has a subtitle but no shape and no accessory, `'image'` has a shape and an accessory but no subtitle, `'condensed'` has all three beside a small image, and `'card'` has a subtitle, a tint and an image mode. `display` is never inherited: it always describes the children of whatever it's set on. On a page or section it lays out that page or section; on a browsable track it declares the layout of the page that track opens — Android Auto needs it there, or that page renders as a list. `gridWrap` is inert unless `display` is `'grid'`. One AAOS caveat: AOSP-based Automotive units honor only the parent item's `display`, so a page mixing grid and list sections renders uniformly there — see [Android Auto → Browse display](/guide/android-auto#browse-display).
579
+
580
+ - **The album line needs `album`.** CarPlay draws the tappable line from the album metadata, so a track with no `album` has no line to tap.
581
+ - **\*Layouts render each platform's nearest supported form.** On CarPlay, a single-line grid (`gridWrap: false`) shows the tiles that fit on one line (about seven on a wide screen, or two condensed cells). A wrapping grid takes as many lines as it needs on iOS 26+, and is a list before that.
582
+ - **Android Auto's grid always wraps**, so it shows more, never less. No car surface scrolls horizontally. An app UI typically renders `gridWrap: false` as a horizontal scroller.
583
+ - **Truncation is visual only.** Tapping a tile queues the whole section (see [Playback behavior](#playback-behavior)).
584
+ - **Item properties are inherited.** `artworkRendering`, `imageShape` and `accessorySymbol` resolve as `track ?? section ?? page`, per property, so an item can override a section-wide value. `accessorySymbol: 'none'` removes an inherited symbol from one item.
585
+ - **The platform places the accessory.** It is trailing on list rows and condensed tiles, and leads the title on image tiles.
586
+ - **On an iOS 26 grid, `gridTile` decides what each tile draws.** `'plain'` has a subtitle but no shape and no accessory. `'image'` has a shape and an accessory but no subtitle. `'condensed'` has all three beside a small image. `'card'` has a subtitle, a tint and an image mode.
587
+ - **`display` is never inherited.** It describes the children of whatever it is set on. On a browsable track it declares the layout of the page the track opens: Android Auto needs it there, or that page renders as a list.
588
+ - **`gridWrap` is inert unless `display` is `'grid'`.**
589
+ - **AAOS honors only the parent item's `display`.** AOSP-based Automotive units render a page that mixes grid and list sections in one layout. See [Android Auto → Browse display](/guide/android-auto#browse-display).
590
+
536
591
  :::
537
592
 
538
593
  ::: tip Inert declarations are logged in debug builds
539
- A combination that can never render — `gridWrap` or `gridTile` outside a grid, `cardTint` with no card treatment in scope, `imageShape` anywhere but an image or condensed grid, `accessorySymbol` on a plain or card grid, `display` on a track that renders playable — is inert, not an error, so nothing breaks. In a **debug build**, each one is logged once per page resolution (`Timber` on Android, `os.log` on iOS) naming the section, the effective style, and the fix:
594
+ Some combinations can never render. They are inert, not errors, so nothing breaks:
595
+
596
+ - `gridWrap` or `gridTile` outside a grid
597
+ - `cardTint` with no card treatment in scope
598
+ - `imageShape` anywhere but an image or condensed grid
599
+ - `accessorySymbol` on a plain or card grid
600
+ - `display` on a track that renders playable
601
+
602
+ In a **debug build**, each one is logged once per page resolution (`Timber` on Android, `os.log` on iOS) naming the section, the effective style, and the fix:
540
603
 
541
604
  ```
542
605
  Inert style declaration on page '/home': `style.gridWrap` on section 'Featured'
@@ -551,14 +614,28 @@ A property a _surface_ can't draw is never reported — that's the aspirational
551
614
  ```ts
552
615
  // A grid page. Android Auto also needs display: 'grid' on the item
553
616
  // that opens this page — see the Android Auto guide:
554
- { path: '/genres', title: 'Genres', style: { display: 'grid' }, children: [...] }
617
+ {
618
+ path: '/genres',
619
+ title: 'Genres',
620
+ style: { display: 'grid' },
621
+ children: [...]
622
+ }
555
623
  {
556
624
  path: '/home',
557
625
  title: 'Home',
558
626
  sections: [
559
- { title: 'Popular', style: { display: 'grid', gridWrap: false }, path: '/popular', children: [...] },
627
+ {
628
+ title: 'Popular',
629
+ style: { display: 'grid', gridWrap: false },
630
+ path: '/popular',
631
+ children: [...]
632
+ },
560
633
  // Round tiles for people: the image tile is the one with a shape.
561
- { title: 'Artists', style: { display: 'grid', gridTile: 'image', imageShape: 'circular' }, children: [...] },
634
+ {
635
+ title: 'Artists',
636
+ style: { display: 'grid', gridTile: 'image', imageShape: 'circular' },
637
+ children: [...]
638
+ },
562
639
  { title: 'All stations', children: [...] }
563
640
  ]
564
641
  }
@@ -570,10 +647,20 @@ A property a _surface_ can't draw is never reported — that's the aspirational
570
647
  ```
571
648
 
572
649
  ::: tip See every style rendered
573
- The example app's **Style Lab** tab draws each `style` declaration on CarPlay: one page per `gridTile` value, plus pages for section headers and for inheritance from page to section to track. Every shelf is titled with the block it renders, so what you see on screen names what to copy. The pages are plain route data in [`style-lab.ts`](https://github.com/radio-garden/react-native-audio-browser/blob/main/apps/example-native/src/utils/style-lab.ts), with a comment on each example saying what it shows.
650
+ The example app's **Style Lab** tab draws each `style` declaration on CarPlay: one page per `gridTile` value, plus pages for section headers and for inheritance from page to section to track.
651
+
652
+ Every shelf is titled with the block it renders, so what you see on screen names what to copy.
653
+
654
+ The pages are plain route data in [`style-lab.ts`](https://github.com/radio-garden/react-native-audio-browser/blob/next/apps/example-native/src/utils/style-lab.ts), with a comment on each example saying what it shows.
574
655
  :::
575
656
 
576
- Two config-level platform options round it out: `carPlayLoadingTitle` (localized "Loading…" on older CarPlay) and `androidControllerOfflineError`. The album-line tap needs both `albumPath` on the track and a `resolveAlbumPath` callback in the config that maps it to a browse path — see [CarPlay](/guide/carplay) and [Android Auto](/guide/android-auto) for the platform setup these build on.
657
+ Three config-level platform options round it out:
658
+
659
+ - `carPlayLoadingTitle`: a localized "Loading…" on older CarPlay.
660
+ - `androidControllerOfflineError`: shows an offline error in Android Auto and other external controllers when the network is lost. It defaults to `true`.
661
+ - [`viewMoreTitle`](/api/types/browser/#viewmoretitle): titles the "view more" row Android Auto appends to a section with a `path`. It is read again on `invalidateAllContent()`.
662
+
663
+ The CarPlay now-playing album line is tappable when the active track has an `albumPath`. For tracks without one, a `resolveAlbumPath` callback maps the track to a browse path. In both cases the track needs an `album`. See [CarPlay](/guide/carplay) and [Android Auto](/guide/android-auto) for the platform setup these build on.
577
664
 
578
665
  ## Where to go next
579
666