0
# UI Customization & Layout
1

2
Advanced customization system for modifying the player's appearance, layout, and individual UI components through custom icons, layouts, and modular UI sections.
3

4
## Required Imports
5

6
```typescript
7
import AudioPlayer, { RHAP_UI } from 'react-h5-audio-player';
8
import { ReactNode, ReactElement } from 'react';
9
```
10

11
## Capabilities
12

13
### Layout Configuration
14

15
Control the overall arrangement and orientation of player components.
16

17
```typescript { .api }
18
type MAIN_LAYOUT = 'stacked' | 'stacked-reverse' | 'horizontal' | 'horizontal-reverse';
19
```
20

21
**Layout Options:**
22
- `'stacked'` (default): Progress bar above controls
23
- `'stacked-reverse'`: Controls above progress bar  
24
- `'horizontal'`: Progress bar and controls side by side
25
- `'horizontal-reverse'`: Controls and progress bar side by side (reversed order)
26

27
### Custom Icons
28

29
Replace default icons with custom React components or elements.
30

31
```typescript { .api }
32
interface CustomIcons {
33
  /** Custom play button icon */
34
  play?: ReactNode;
35
  /** Custom pause button icon */
36
  pause?: ReactNode;
37
  /** Custom rewind button icon */
38
  rewind?: ReactNode;
39
  /** Custom forward button icon */
40
  forward?: ReactNode;
41
  /** Custom previous track button icon */
42
  previous?: ReactNode;
43
  /** Custom next track button icon */
44
  next?: ReactNode;
45
  /** Custom loop enabled icon */
46
  loop?: ReactNode;
47
  /** Custom loop disabled icon */
48
  loopOff?: ReactNode;
49
  /** Custom volume button icon */
50
  volume?: ReactNode;
51
  /** Custom mute button icon */
52
  volumeMute?: ReactNode;
53
}
54
```
55

56
### UI Module System
57

58
The player uses a modular UI system where individual components can be customized or rearranged.
59

60
```typescript { .api }
61
enum RHAP_UI {
62
  CURRENT_TIME = 'CURRENT_TIME',
63
  CURRENT_LEFT_TIME = 'CURRENT_LEFT_TIME', 
64
  PROGRESS_BAR = 'PROGRESS_BAR',
65
  DURATION = 'DURATION',
66
  ADDITIONAL_CONTROLS = 'ADDITIONAL_CONTROLS',
67
  MAIN_CONTROLS = 'MAIN_CONTROLS',
68
  VOLUME_CONTROLS = 'VOLUME_CONTROLS',
69
  LOOP = 'LOOP',
70
  VOLUME = 'VOLUME'
71
}
72

73
type CustomUIModule = RHAP_UI | ReactElement;
74
type CustomUIModules = Array<CustomUIModule>;
75
```
76

77
### Custom UI Sections
78

79
Customize the arrangement of UI components in different sections of the player.
80

81
```typescript { .api }
82
interface CustomUISections {
83
  /** Customize the progress bar section layout */
84
  customProgressBarSection?: CustomUIModules;
85
  /** Customize the main controls section layout */
86
  customControlsSection?: CustomUIModules;
87
  /** Customize additional controls (like loop button) */
88
  customAdditionalControls?: CustomUIModules;
89
  /** Customize volume controls section */
90
  customVolumeControls?: CustomUIModules;
91
}
92
```
93

94
**Default Configurations:**
95
- `customProgressBarSection`: `[RHAP_UI.CURRENT_TIME, RHAP_UI.PROGRESS_BAR, RHAP_UI.DURATION]`
96
- `customControlsSection`: `[RHAP_UI.ADDITIONAL_CONTROLS, RHAP_UI.MAIN_CONTROLS, RHAP_UI.VOLUME_CONTROLS]`
97
- `customAdditionalControls`: `[RHAP_UI.LOOP]`
98
- `customVolumeControls`: `[RHAP_UI.VOLUME]`
99

100
### Time Display Configuration
101

102
Control how time values are formatted and displayed.
103

104
```typescript { .api }
105
type TIME_FORMAT = 'auto' | 'mm:ss' | 'hh:mm:ss';
106
```
107

108
**Time Format Options:**
109
- `'auto'`: Automatically choose mm:ss or hh:mm:ss based on duration
110
- `'mm:ss'`: Always use minutes:seconds format
111
- `'hh:mm:ss'`: Always use hours:minutes:seconds format
112

113
### Internationalization Support
114

115
Customize accessibility labels for screen readers and internationalization.
116

117
```typescript { .api }
118
interface I18nAriaLabels {
119
  /** Main player container label */
120
  player?: string;
121
  /** Progress bar control label */
122
  progressControl?: string;
123
  /** Volume control label */
124
  volumeControl?: string;
125
  /** Play button label */
126
  play?: string;
127
  /** Pause button label */
128
  pause?: string;
129
  /** Rewind button label */
130
  rewind?: string;
131
  /** Forward button label */
132
  forward?: string;
133
  /** Previous track button label */
134
  previous?: string;
135
  /** Next track button label */
136
  next?: string;
137
  /** Loop enabled button label */
138
  loop?: string;
139
  /** Loop disabled button label */
140
  loopOff?: string;
141
  /** Volume button label */
142
  volume?: string;
143
  /** Mute button label */
144
  volumeMute?: string;
145
}
146
```
147

148
**Default English Labels:**
149
```typescript
150
const defaultI18nAriaLabels: I18nAriaLabels = {
151
  player: 'Audio player',
152
  progressControl: 'Audio progress control',
153
  volumeControl: 'Volume control',
154
  play: 'Play',
155
  pause: 'Pause',
156
  rewind: 'Rewind',
157
  forward: 'Forward',
158
  previous: 'Previous',
159
  next: 'Skip',
160
  loop: 'Disable loop',
161
  loopOff: 'Enable loop',
162
  volume: 'Mute',
163
  volumeMute: 'Unmute'
164
};
165
```
166

167
## Usage Examples
168

169
**Custom Layout Configuration:**
170

171
```typescript
172
<AudioPlayer
173
  src="audio.mp3"
174
  layout="horizontal"
175
  timeFormat="hh:mm:ss"
176
  showJumpControls={true}
177
  showSkipControls={true}
178
/>
179
```
180

181
**Custom Icons:**
182

183
```typescript
184
import { FaPlay, FaPause, FaStepForward, FaStepBackward } from 'react-icons/fa';
185

186
<AudioPlayer
187
  src="audio.mp3"
188
  customIcons={{
189
    play: <FaPlay />,
190
    pause: <FaPause />,
191
    previous: <FaStepBackward />,
192
    next: <FaStepForward />
193
  }}
194
/>
195
```
196

197
**Custom UI Section Layout:**
198

199
```typescript
200
<AudioPlayer
201
  src="audio.mp3"
202
  customProgressBarSection={[
203
    RHAP_UI.CURRENT_LEFT_TIME,  // Show remaining time instead
204
    RHAP_UI.PROGRESS_BAR,
205
    RHAP_UI.DURATION
206
  ]}
207
  customControlsSection={[
208
    RHAP_UI.VOLUME_CONTROLS,    // Volume controls on left
209
    RHAP_UI.MAIN_CONTROLS,      // Play/pause in center
210
    RHAP_UI.ADDITIONAL_CONTROLS // Loop on right
211
  ]}
212
/>
213
```
214

215
**Custom Components in UI:**
216

217
```typescript
218
const CustomTrackInfo = () => (
219
  <div className="track-info">
220
    <span>Track 1 of 10</span>
221
  </div>
222
);
223

224
<AudioPlayer
225
  src="audio.mp3"
226
  customAdditionalControls={[
227
    <CustomTrackInfo key="track-info" />,
228
    RHAP_UI.LOOP
229
  ]}
230
/>
231
```
232

233
**Internationalization:**
234

235
```typescript
236
<AudioPlayer
237
  src="audio.mp3"
238
  i18nAriaLabels={{
239
    player: 'Lecteur audio',
240
    play: 'Jouer',
241
    pause: 'Pause',
242
    rewind: 'Retour rapide',
243
    forward: 'Avance rapide',
244
    volume: 'Muet',
245
    volumeMute: 'Activer le son'
246
  }}
247
/>
248
```
249

250
**Minimal Player (Progress Only):**
251

252
```typescript
253
<AudioPlayer
254
  src="audio.mp3"
255
  customProgressBarSection={[RHAP_UI.PROGRESS_BAR]}
256
  customControlsSection={[]}
257
  showJumpControls={false}
258
/>
259
```
260

261
**Full-Featured Player:**
262

263
```typescript
264
<AudioPlayer
265
  src="audio.mp3"
266
  layout="horizontal"
267
  showSkipControls={true}
268
  showJumpControls={true}
269
  showFilledProgress={true}
270
  showFilledVolume={true}
271
  timeFormat="auto"
272
  header={<h3>Now Playing: Song Title</h3>}
273
  footer={<p>Artist Name - Album Name</p>}
274
  customIcons={{
275
    play: <CustomPlayIcon />,
276
    pause: <CustomPauseIcon />
277
  }}
278
  customAdditionalControls={[
279
    <CustomRatingWidget key="rating" />,
280
    RHAP_UI.LOOP,
281
    <CustomShareButton key="share" />
282
  ]}
283
/>
284
```
285

286
**Styling and CSS Classes:**
287

288
The player adds various CSS classes for styling:
289

290
```css
291
/* Main container classes */
292
.rhap_container { /* Main player container */ }
293
.rhap_stacked { /* Stacked layout */ }
294
.rhap_horizontal { /* Horizontal layout */ }
295
.rhap_play-status--playing { /* When playing */ }
296
.rhap_play-status--paused { /* When paused */ }
297
.rhap_loop--on { /* When loop is enabled */ }
298
.rhap_loop--off { /* When loop is disabled */ }
299

300
/* Component classes */
301
.rhap_progress-section { /* Progress bar section */ }
302
.rhap_controls-section { /* Controls section */ }
303
.rhap_main-controls { /* Play/pause/skip buttons */ }
304
.rhap_volume-controls { /* Volume controls */ }
305
.rhap_additional-controls { /* Additional controls like loop */ }
306
```
307

308
Custom styling can be applied by importing your own CSS after the default styles:
309

310
```typescript
311
import 'react-h5-audio-player/lib/styles.css';
312
import './custom-player-styles.css'; // Your custom styles
313
```