0
# Text Components
1

2
Core text component system providing immutable, type-safe text objects with rich formatting, events, and styling capabilities. Components are the fundamental building blocks for all text display in Adventure.
3

4
## Capabilities
5

6
### Component Interface
7

8
The root interface for all text components, providing common functionality for styling, events, and composition.
9

10
```java { .api }
11
/**
12
 * Root interface for all text components - immutable text with styling and events
13
 */
14
interface Component extends ComponentLike, Examinable, HoverEventSource<Component>, StyleGetter, StyleSetter<Component> {
15
    // Factory methods for creating components
16
    static Component empty();
17
    static Component newline();
18
    static Component space();
19
    static TextComponent text(String content);
20
    static TextComponent text(String content, TextColor color);
21
    static TextComponent text(String content, TextColor color, TextDecoration... decorations);
22
    static TranslatableComponent translatable(String key);
23
    static TranslatableComponent translatable(String key, ComponentLike... arguments);
24
    static KeybindComponent keybind(String keybind);
25
    static ScoreComponent score(String name, String objective);
26
    static SelectorComponent selector(String pattern);
27
    static BlockNBTComponent blockNBT(String nbtPath, BlockNBTComponent.Pos pos);
28
    static EntityNBTComponent entityNBT(String nbtPath, String selector);
29
    static StorageNBTComponent storageNBT(String nbtPath, Key storage);
30
    
31
    // Component joining and composition
32
    static Component join(ComponentLike separator, ComponentLike... components);
33
    static Component join(ComponentLike separator, Iterable<? extends ComponentLike> components);
34
    static Component join(JoinConfiguration configuration, ComponentLike... components);
35
    static Component join(JoinConfiguration configuration, Iterable<? extends ComponentLike> components);
36
    
37
    // Component properties and manipulation
38
    List<Component> children();
39
    Component children(List<? extends ComponentLike> children);
40
    boolean hasStyling();
41
    Component append(Component component);
42
    Component append(ComponentLike component);
43
    Component appendSpace();
44
    Component appendNewline();
45
    
46
    // Text replacement and processing
47
    Component replaceText(TextReplacementConfig config);
48
    Component replaceText(Pattern pattern, ComponentLike replacement);
49
    Component replaceText(String search, ComponentLike replacement);
50
    
51
    // Component iteration and inspection
52
    Iterable<Component> iterable(ComponentIteratorType type, ComponentIteratorFlag... flags);
53
    void detectUrls(UrlConsumer action);
54
    
55
    // Compact representation
56
    Component compact();
57
}
58
```
59

60
### Text Component
61

62
Component containing plain text content with full styling support.
63

64
```java { .api }
65
/**
66
 * Component with plain string content
67
 */
68
interface TextComponent extends BuildableComponent<TextComponent, TextComponent.Builder> {
69
    /**
70
     * Gets the plain text content
71
     * @return the text content
72
     */
73
    String content();
74
    
75
    /**
76
     * Sets the text content
77
     * @param content the new content
78
     * @return component with new content
79
     */
80
    TextComponent content(String content);
81
    
82
    /**
83
     * Builder for creating text components
84
     */
85
    interface Builder extends ComponentBuilder<TextComponent, Builder> {
86
        /**
87
         * Sets the text content
88
         * @param content the content
89
         * @return this builder
90
         */
91
        Builder content(String content);
92
    }
93
}
94
```
95

96
**Usage Examples:**
97

98
```java
99
import net.kyori.adventure.text.Component;
100
import net.kyori.adventure.text.format.NamedTextColor;
101
import net.kyori.adventure.text.format.TextDecoration;
102

103
// Simple text
104
Component simple = Component.text("Hello World!");
105

106
// Text with color
107
Component colored = Component.text("Red text", NamedTextColor.RED);
108

109
// Text with multiple decorations
110
Component decorated = Component.text("Bold italic text", NamedTextColor.BLUE, TextDecoration.BOLD, TextDecoration.ITALIC);
111

112
// Using builder pattern
113
Component complex = Component.text()
114
    .content("Complex text")
115
    .color(NamedTextColor.GREEN)
116
    .decorate(TextDecoration.UNDERLINED)
117
    .append(Component.space())
118
    .append(Component.text("with more", NamedTextColor.YELLOW))
119
    .build();
120
```
121

122
### Translatable Component
123

124
Component that displays translated text based on the client's locale and registered translations.
125

126
```java { .api }
127
/**
128
 * Component that displays translated text
129
 */
130
interface TranslatableComponent extends BuildableComponent<TranslatableComponent, TranslatableComponent.Builder> {
131
    /**
132
     * Gets the translation key
133
     * @return the translation key
134
     */
135
    String key();
136
    
137
    /**
138
     * Sets the translation key
139
     * @param key the translation key
140
     * @return component with new key
141
     */
142
    TranslatableComponent key(String key);
143
    
144
    /**
145
     * Gets the translation arguments
146
     * @return list of translation arguments
147
     */
148
    List<TranslationArgument> arguments();
149
    
150
    /**
151
     * Sets the translation arguments
152
     * @param arguments the arguments
153
     * @return component with new arguments
154
     */
155
    TranslatableComponent arguments(List<? extends TranslationArgumentLike> arguments);
156
    TranslatableComponent arguments(TranslationArgumentLike... arguments);
157
    
158
    /**
159
     * Gets the fallback string used when translation is not available
160
     * @return the fallback string or null
161
     */
162
    @Nullable String fallback();
163
    
164
    /**
165
     * Sets the fallback string
166
     * @param fallback the fallback string
167
     * @return component with new fallback
168
     */
169
    TranslatableComponent fallback(@Nullable String fallback);
170
    
171
    interface Builder extends ComponentBuilder<TranslatableComponent, Builder> {
172
        Builder key(String key);
173
        Builder arguments(List<? extends TranslationArgumentLike> arguments);
174
        Builder arguments(TranslationArgumentLike... arguments);
175
        Builder fallback(@Nullable String fallback);
176
    }
177
}
178
```
179

180
**Usage Examples:**
181

182
```java
183
// Basic translation
184
Component welcome = Component.translatable("welcome.message");
185

186
// Translation with arguments
187
Component playerJoined = Component.translatable("player.joined", 
188
    Component.text("PlayerName", NamedTextColor.YELLOW));
189

190
// Translation with fallback
191
Component withFallback = Component.translatable()
192
    .key("custom.message")
193
    .fallback("Default message")
194
    .arguments(Component.text("arg1"))
195
    .build();
196
```
197

198
### Keybind Component
199

200
Component that displays the name of a keybind as configured by the client.
201

202
```java { .api }
203
/**
204
 * Component displaying a keybind name
205
 */
206
interface KeybindComponent extends BuildableComponent<KeybindComponent, KeybindComponent.Builder> {
207
    /**
208
     * Gets the keybind identifier
209
     * @return the keybind string
210
     */
211
    String keybind();
212
    
213
    /**
214
     * Sets the keybind identifier
215
     * @param keybind the keybind string
216
     * @return component with new keybind
217
     */
218
    KeybindComponent keybind(String keybind);
219
    
220
    interface Builder extends ComponentBuilder<KeybindComponent, Builder> {
221
        Builder keybind(String keybind);
222
    }
223
}
224
```
225

226
**Usage Examples:**
227

228
```java
229
// Show jump key
230
Component jumpKey = Component.keybind("key.jump");
231

232
// Show attack key in context
233
Component instruction = Component.text("Press ")
234
    .append(Component.keybind("key.attack").color(NamedTextColor.YELLOW))
235
    .append(Component.text(" to attack"));
236
```
237

238
### Score Component
239

240
Component that displays a value from the scoreboard system.
241

242
```java { .api }
243
/**
244
 * Component displaying a scoreboard value
245
 */
246
interface ScoreComponent extends BuildableComponent<ScoreComponent, ScoreComponent.Builder> {
247
    /**
248
     * Gets the score holder name (player name, selector, etc.)
249
     * @return the name
250
     */
251
    String name();
252
    
253
    /**
254
     * Sets the score holder name
255
     * @param name the name
256
     * @return component with new name
257
     */
258
    ScoreComponent name(String name);
259
    
260
    /**
261
     * Gets the objective name
262
     * @return the objective
263
     */
264
    String objective();
265
    
266
    /**
267
     * Sets the objective name
268
     * @param objective the objective
269
     * @return component with new objective
270
     */
271
    ScoreComponent objective(String objective);
272
    
273
    /**
274
     * Gets the optional fixed value override
275
     * @return the value or null
276
     */
277
    @Nullable String value();
278
    
279
    /**
280
     * Sets a fixed value override
281
     * @param value the value or null to use scoreboard
282
     * @return component with new value
283
     */
284
    ScoreComponent value(@Nullable String value);
285
    
286
    interface Builder extends ComponentBuilder<ScoreComponent, Builder> {
287
        Builder name(String name);
288
        Builder objective(String objective);
289
        Builder value(@Nullable String value);
290
    }
291
}
292
```
293

294
### Selector Component
295

296
Component that resolves entity selectors and displays their names or count.
297

298
```java { .api }
299
/**
300
 * Component using entity selector patterns
301
 */
302
interface SelectorComponent extends BuildableComponent<SelectorComponent, SelectorComponent.Builder> {
303
    /**
304
     * Gets the selector pattern
305
     * @return the selector string
306
     */
307
    String pattern();
308
    
309
    /**
310
     * Sets the selector pattern
311
     * @param pattern the selector
312
     * @return component with new pattern
313
     */
314
    SelectorComponent pattern(String pattern);
315
    
316
    /**
317
     * Gets the separator used between multiple results
318
     * @return the separator component or null
319
     */
320
    @Nullable Component separator();
321
    
322
    /**
323
     * Sets the separator for multiple results  
324
     * @param separator the separator or null
325
     * @return component with new separator
326
     */
327
    SelectorComponent separator(@Nullable ComponentLike separator);
328
    
329
    interface Builder extends ComponentBuilder<SelectorComponent, Builder> {
330
        Builder pattern(String pattern);
331
        Builder separator(@Nullable ComponentLike separator);
332
    }
333
}
334
```
335

336
### Component Builders
337

338
All buildable components implement the common builder pattern for fluent construction.
339

340
```java { .api }
341
/**
342
 * Base interface for component builders
343
 */
344
interface ComponentBuilder<C extends Component, B extends ComponentBuilder<C, B>> 
345
    extends AbstractBuilder<C>, ComponentBuilderApplicable, StyleSetter<B> {
346
    
347
    /**
348
     * Appends a component to the children list
349
     * @param component the component to append
350
     * @return this builder
351
     */
352
    B append(Component component);
353
    B append(ComponentLike component);
354
    B appendSpace();
355
    B appendNewline();
356
    
357
    /**
358
     * Sets the children list
359
     * @param children the children components
360
     * @return this builder
361
     */
362
    B children(List<? extends ComponentLike> children);
363
    
364
    /**
365
     * Applies a style configurator
366
     * @param styleApplicable the style to apply
367
     * @return this builder
368
     */
369
    B style(StyleBuilderApplicable styleApplicable);
370
    
371
    /**
372
     * Builds the final component
373
     * @return the built component
374
     */
375
    C build();
376
}
377

378
/**
379
 * Specialized builder for NBT components
380
 */
381
interface NBTComponentBuilder<C extends NBTComponent<C, B>, B extends NBTComponentBuilder<C, B>> 
382
    extends ComponentBuilder<C, B> {
383
    
384
    /**
385
     * Sets the NBT path expression
386
     * @param nbtPath the path
387
     * @return this builder
388
     */
389
    B nbtPath(String nbtPath);
390
    
391
    /**
392
     * Sets whether to interpret NBT as components
393
     * @param interpret whether to interpret
394
     * @return this builder
395
     */
396
    B interpret(boolean interpret);
397
    
398
    /**
399
     * Sets the separator for multiple NBT results
400
     * @param separator the separator or null
401
     * @return this builder
402
     */
403
    B separator(@Nullable ComponentLike separator);
404
}
405
```
406

407
## Component Utility Classes
408

409
### Linear Components
410

411
Utilities for working with sequences of components as linear text.
412

413
```java { .api }
414
/**
415
 * Utilities for linear component operations
416
 */
417
class LinearComponents {
418
    /**
419
     * Collects components into a linear sequence
420
     * @return collector for components
421
     */
422
    static Collector<Component, ?, Component> toLinearComponents();
423
    
424
    /**
425
     * Creates a linear component from components
426
     * @param components the components
427
     * @return linear component
428
     */
429
    static Component linear(ComponentLike... components);
430
}
431
```
432

433
### Join Configuration  
434

435
Configuration for component joining operations with customizable separators and formatting.
436

437
```java { .api }
438
/**
439
 * Configuration for joining components
440
 */
441
interface JoinConfiguration extends Examinable {
442
    /**
443
     * Gets the separator used between components
444
     * @return the separator
445
     */
446
    ComponentLike separator();
447
    
448
    /**
449
     * Gets the last separator (used before final component)
450
     * @return the last separator or null to use normal separator
451
     */
452
    @Nullable ComponentLike lastSeparator();
453
    
454
    /**
455
     * Gets the separator for exactly two components
456
     * @return the two separator or null to use normal separator
457
     */
458
    @Nullable ComponentLike lastSeparatorIfTwo();
459
    
460
    /**
461
     * Gets the prefix applied to the joined result
462
     * @return the prefix or null
463
     */
464
    @Nullable ComponentLike prefix();
465
    
466
    /**
467
     * Gets the suffix applied to the joined result  
468
     * @return the suffix or null
469
     */
470
    @Nullable ComponentLike suffix();
471
    
472
    /**
473
     * Creates join configuration
474
     * @param separator the separator
475
     * @return new configuration
476
     */
477
    static JoinConfiguration separator(ComponentLike separator);
478
    
479
    /**
480
     * Creates builder for join configuration
481
     * @return new builder
482
     */
483
    static Builder builder();
484
    
485
    interface Builder extends AbstractBuilder<JoinConfiguration> {
486
        Builder separator(ComponentLike separator);
487
        Builder lastSeparator(@Nullable ComponentLike lastSeparator);
488
        Builder lastSeparatorIfTwo(@Nullable ComponentLike lastSeparatorIfTwo);
489
        Builder prefix(@Nullable ComponentLike prefix);
490
        Builder suffix(@Nullable ComponentLike suffix);
491
    }
492
}
493
```
494

495
## Types and Interfaces
496

497
### Component-Like Types
498

499
```java { .api }
500
/**
501
 * Objects that can be converted to components
502
 */
503
interface ComponentLike {
504
    /**
505
     * Converts this object to a component
506
     * @return the component representation
507
     */
508
    Component asComponent();
509
}
510

511
/**
512
 * Objects that can be applied to components
513
 */
514
interface ComponentApplicable {
515
    /**
516
     * Applies this object to a component
517
     * @param component the target component
518
     * @return the modified component
519
     */
520
    Component componentApply(Component component);
521
}
522

523
/**
524
 * Objects that can be applied to component builders
525
 */
526
interface ComponentBuilderApplicable {
527
    /**
528
     * Applies this object to a component builder
529
     * @param builder the target builder
530
     */
531
    <B extends ComponentBuilder<?, B>> void componentBuilderApply(B builder);
532
}
533
```
534

535
### Build Pattern Interfaces
536

537
```java { .api }
538
/**
539
 * Base interface for buildable components
540
 */
541
interface BuildableComponent<C extends BuildableComponent<C, B>, B extends ComponentBuilder<C, B>> 
542
    extends Component {
543
    
544
    /**
545
     * Creates a builder pre-populated with this component's values
546
     * @return new builder
547
     */
548
    B toBuilder();
549
}
550

551
/**
552
 * Base builder interface
553
 */
554
interface AbstractBuilder<R> {
555
    /**
556
     * Builds the final result
557
     * @return the built object
558
     */
559
    R build();
560
}
561
```
562

563
### Iteration and Processing
564

565
```java { .api }
566
/**
567
 * Types of component iteration
568
 */
569
interface ComponentIteratorType {
570
    ComponentIteratorType DEPTH_FIRST = ComponentIteratorType.create("depth_first");
571
    ComponentIteratorType BREADTH_FIRST = ComponentIteratorType.create("breadth_first");
572
    
573
    static ComponentIteratorType create(String name);
574
}
575

576
/**
577
 * Flags for component iteration behavior
578
 */
579
enum ComponentIteratorFlag {
580
    /**
581
     * Include the root component in iteration
582
     */
583
    INCLUDE_TRANSLATABLE_COMPONENT_ARGUMENTS
584
}
585

586
/**
587
 * Consumer for URL detection in components
588
 */
589
interface UrlConsumer {
590
    /**
591
     * Called when a URL is detected
592
     * @param url the detected URL
593
     */
594
    void accept(String url);
595
}
596
```