0
# Titles and Subtitles
1

2
Title display system with customizable timing, main titles, subtitles, and action bar text. Titles provide prominent on-screen text display for important messages and events.
3

4
## Capabilities
5

6
### Title Interface
7

8
Core interface for creating and displaying titles with main title, subtitle, and timing configuration.
9

10
```java { .api }
11
/**
12
 * Represents a title display with main title, subtitle, and timing
13
 */
14
interface Title extends Examinable {
15
    /**
16
     * Gets the main title text
17
     * @return the title component
18
     */
19
    Component title();
20
    
21
    /**
22
     * Gets the subtitle text
23
     * @return the subtitle component
24
     */
25
    Component subtitle();
26
    
27
    /**
28
     * Gets the title timing configuration
29
     * @return the times or null for default
30
     */
31
    @Nullable Times times();
32
    
33
    /**
34
     * Creates a title with main title and subtitle
35
     * @param title the main title
36
     * @param subtitle the subtitle
37
     * @return new title
38
     */
39
    static Title title(ComponentLike title, ComponentLike subtitle);
40
    
41
    /**
42
     * Creates a title with timing
43
     * @param title the main title
44
     * @param subtitle the subtitle
45
     * @param times the timing configuration
46
     * @return new title
47
     */
48
    static Title title(ComponentLike title, ComponentLike subtitle, @Nullable Times times);
49
    
50
    /**
51
     * Title timing configuration
52
     */
53
    class Times implements Examinable {
54
        /**
55
         * Gets the fade in duration
56
         * @return fade in duration
57
         */
58
        Duration fadeIn();
59
        
60
        /**
61
         * Gets the stay duration
62
         * @return stay duration
63
         */
64
        Duration stay();
65
        
66
        /**
67
         * Gets the fade out duration
68
         * @return fade out duration
69
         */
70
        Duration fadeOut();
71
        
72
        /**
73
         * Creates title timing
74
         * @param fadeIn fade in duration
75
         * @param stay stay duration
76
         * @param fadeOut fade out duration
77
         * @return new timing configuration
78
         */
79
        static Times times(Duration fadeIn, Duration stay, Duration fadeOut);
80
        
81
        /**
82
         * Creates timing with tick values
83
         * @param fadeInTicks fade in ticks
84
         * @param stayTicks stay ticks
85
         * @param fadeOutTicks fade out ticks
86
         * @return new timing configuration
87
         */
88
        static Times of(int fadeInTicks, int stayTicks, int fadeOutTicks);
89
        
90
        /**
91
         * Default title timing
92
         * @return default times (1s fade in, 3s stay, 1s fade out)
93
         */
94
        static Times defaultTimes();
95
    }
96
}
97
```
98

99
### Title Parts
100

101
Individual title components that can be sent separately for incremental updates.
102

103
```java { .api }
104
/**
105
 * Individual part of a title for separate updates
106
 */
107
interface TitlePart<T> {
108
    /**
109
     * Gets the part value
110
     * @return the value
111
     */
112
    T value();
113
    
114
    /**
115
     * Creates a main title part
116
     * @param title the title text
117
     * @return title part
118
     */
119
    static TitlePart<Component> title(ComponentLike title);
120
    
121
    /**
122
     * Creates a subtitle part
123
     * @param subtitle the subtitle text
124
     * @return subtitle part
125
     */
126
    static TitlePart<Component> subtitle(ComponentLike subtitle);
127
    
128
    /**
129
     * Creates a timing part
130
     * @param times the timing configuration
131
     * @return timing part
132
     */
133
    static TitlePart<Title.Times> times(Title.Times times);
134
}
135
```
136

137
**Usage Examples:**
138

139
```java
140
import net.kyori.adventure.title.Title;
141
import net.kyori.adventure.title.TitlePart;
142
import net.kyori.adventure.text.Component;
143
import net.kyori.adventure.text.format.NamedTextColor;
144
import java.time.Duration;
145

146
// Simple title
147
Title welcome = Title.title(
148
    Component.text("Welcome!", NamedTextColor.GOLD),
149
    Component.text("Enjoy your stay", NamedTextColor.YELLOW)
150
);
151
audience.showTitle(welcome);
152

153
// Title with custom timing
154
Title announcement = Title.title(
155
    Component.text("Server Restart", NamedTextColor.RED),
156
    Component.text("In 5 minutes", NamedTextColor.WHITE),
157
    Title.Times.times(
158
        Duration.ofMillis(500),  // 0.5s fade in
159
        Duration.ofSeconds(5),   // 5s stay
160
        Duration.ofSeconds(1)    // 1s fade out
161
    )
162
);
163

164
// Update title parts separately
165
audience.sendTitlePart(TitlePart.title(Component.text("Updated Title")));
166
audience.sendTitlePart(TitlePart.subtitle(Component.text("New subtitle")));
167

168
// Quick timing for urgent messages
169
Title urgent = Title.title(
170
    Component.text("DANGER!", NamedTextColor.DARK_RED),
171
    Component.text("Move away immediately", NamedTextColor.RED),
172
    Title.Times.times(
173
        Duration.ofMillis(100),  // Fast fade in
174
        Duration.ofSeconds(2),   // Short display
175
        Duration.ofMillis(300)   // Quick fade out
176
    )
177
);
178

179
// Clear and reset titles
180
audience.clearTitle();  // Clear current title
181
audience.resetTitle();  // Clear and reset timing
182
```
183

184
## Common Title Patterns
185

186
### Event Announcements
187

188
```java
189
public class TitleAnnouncements {
190
    public static void showPlayerJoin(Audience audience, String playerName) {
191
        Title joinTitle = Title.title(
192
            Component.text(playerName + " joined!", NamedTextColor.GREEN),
193
            Component.text("Welcome to the server", NamedTextColor.GRAY)
194
        );
195
        audience.showTitle(joinTitle);
196
    }
197
    
198
    public static void showLevelUp(Audience audience, int level) {
199
        Title levelTitle = Title.title(
200
            Component.text("Level Up!", NamedTextColor.GOLD),
201
            Component.text("Level " + level, NamedTextColor.YELLOW),
202
            Title.Times.times(Duration.ofSeconds(1), Duration.ofSeconds(2), Duration.ofSeconds(1))
203
        );
204
        audience.showTitle(levelTitle);
205
    }
206
    
207
    public static void showCountdown(Audience audience, int seconds) {
208
        Component countdownText = Component.text(
209
            String.valueOf(seconds), 
210
            seconds <= 3 ? NamedTextColor.RED : NamedTextColor.YELLOW
211
        );
212
        
213
        Title countdown = Title.title(
214
            countdownText,
215
            Component.text("Get ready!", NamedTextColor.WHITE),
216
            Title.Times.times(Duration.ofMillis(200), Duration.ofMillis(800), Duration.ofMillis(200))
217
        );
218
        audience.showTitle(countdown);
219
    }
220
}
221
```
222

223
### Progressive Title Updates
224

225
```java
226
// Countdown sequence
227
public void startCountdown(Audience audience, int startSeconds) {
228
    for (int i = startSeconds; i > 0; i--) {
229
        final int seconds = i;
230
        scheduleTask(() -> {
231
            Component countText = Component.text(String.valueOf(seconds))
232
                .color(seconds <= 3 ? NamedTextColor.RED : NamedTextColor.YELLOW);
233
            audience.sendTitlePart(TitlePart.title(countText));
234
        }, (startSeconds - i) * 1000L); // 1 second intervals
235
    }
236
    
237
    // Final "GO!" message
238
    scheduleTask(() -> {
239
        Title goTitle = Title.title(
240
            Component.text("GO!", NamedTextColor.GREEN),
241
            Component.empty()
242
        );
243
        audience.showTitle(goTitle);
244
    }, startSeconds * 1000L);
245
}
246

247
// Health status updates
248
public void updateHealthTitle(Audience audience, double health, double maxHealth) {
249
    double percentage = health / maxHealth;
250
    NamedTextColor color;
251
    
252
    if (percentage > 0.6) color = NamedTextColor.GREEN;
253
    else if (percentage > 0.3) color = NamedTextColor.YELLOW;  
254
    else color = NamedTextColor.RED;
255
    
256
    Component healthText = Component.text()
257
        .append(Component.text("Health: ", NamedTextColor.WHITE))
258
        .append(Component.text(String.format("%.0f", health), color))
259
        .append(Component.text("/", NamedTextColor.GRAY))
260
        .append(Component.text(String.format("%.0f", maxHealth), NamedTextColor.WHITE))
261
        .build();
262
    
263
    audience.sendTitlePart(TitlePart.subtitle(healthText));
264
}
265
```
266

267
### Timed Information Display
268

269
```java
270
public class TimedTitles {
271
    // Show temporary information
272
    public static void showTemporaryInfo(Audience audience, Component info, Duration displayTime) {
273
        Title infoTitle = Title.title(
274
            info,
275
            Component.empty(),
276
            Title.Times.times(
277
                Duration.ofMillis(300),
278
                displayTime,
279
                Duration.ofMillis(300)
280
            )
281
        );
282
        audience.showTitle(infoTitle);
283
    }
284
    
285
    // Achievement notification
286
    public static void showAchievement(Audience audience, String achievementName) {
287
        Title achievement = Title.title(
288
            Component.text("Achievement Unlocked!", NamedTextColor.GOLD),
289
            Component.text(achievementName, NamedTextColor.YELLOW),
290
            Title.Times.times(
291
                Duration.ofSeconds(1),
292
                Duration.ofSeconds(4),
293
                Duration.ofSeconds(1)
294
            )
295
        );
296
        audience.showTitle(achievement);
297
    }
298
    
299
    // Warning message with urgency
300
    public static void showWarning(Audience audience, String warning, boolean urgent) {
301
        Duration fadeIn = urgent ? Duration.ofMillis(100) : Duration.ofMillis(500);
302
        Duration stay = urgent ? Duration.ofSeconds(3) : Duration.ofSeconds(5);
303
        Duration fadeOut = urgent ? Duration.ofMillis(200) : Duration.ofSeconds(1);
304
        
305
        Title warningTitle = Title.title(
306
            Component.text("WARNING", urgent ? NamedTextColor.DARK_RED : NamedTextColor.RED),
307
            Component.text(warning, NamedTextColor.WHITE),
308
            Title.Times.times(fadeIn, stay, fadeOut)
309
        );
310
        audience.showTitle(warningTitle);
311
    }
312
}
313
```