Label
A versatile label component for displaying text with support for secondary text, highlighting, masking, and customizable styling. Perfect for form labels, captions, and general text display with optional/required indicators.
Import
rust
use gpui_component::label::{Label, HighlightsMatch};
Usage
Basic Label
rust
Label::new("This is a label")
Label with Secondary Text
rust
// Label with optional indicator
Label::new("Company Address")
.secondary("(optional)")
// Label with required indicator
Label::new("Email Address")
.secondary("(required)")
Text Alignment
rust
// Left aligned (default)
Label::new("Text align left")
// Center aligned
Label::new("Text align center")
.text_center()
// Right aligned
Label::new("Text align right")
.text_right()
Text Highlighting
rust
// Full text highlighting (finds all matches)
Label::new("Hello World Hello")
.highlights("Hello")
// Prefix highlighting (only matches at start)
Label::new("Hello World")
.highlights(HighlightsMatch::Prefix("Hello".into()))
// Highlight with secondary text
Label::new("Company Name")
.secondary("(optional)")
.highlights("Company")
Color and Styling
rust
use gpui_component::green_500;
// Custom text color
Label::new("Color Label")
.text_color(green_500())
// Font styling
Label::new("Font Size Label")
.text_size(px(20.))
.font_semibold()
.line_height(rems(1.8))
Masked Labels
rust
// For sensitive information
Label::new("9,182,1 USD")
.text_2xl()
.masked(true) // Shows as "•••••••••••"
// Toggle masking programmatically
Label::new("500 USD")
.text_xl()
.masked(self.masked)
Multi-line Text
rust
// Text wrapping with line height
div().w(px(200.)).child(
Label::new(
"Label should support text wrap in default, \
if the text is too long, it should wrap to the next line."
)
.line_height(rems(1.8))
)
Different Sizes
rust
// Using text size utilities
Label::new("Extra Large").text_2xl()
Label::new("Large").text_xl()
Label::new("Medium").text_base() // default
Label::new("Small").text_sm()
Label::new("Extra Small").text_xs()
API Reference
Label
Method | Description |
---|---|
new(text) | Create a new label with text |
secondary(text) | Add secondary text (usually for optional/required indicators) |
masked(bool) | Show/hide text with bullet characters |
highlights(match) | Highlight matching text |
HighlightsMatch
Variant | Description |
---|---|
Full(text) | Highlights all occurrences of the text |
Prefix(text) | Highlights only if text appears at the beginning |
Method | Description |
---|---|
as_str() | Get the search text as string |
is_prefix() | Check if this is a prefix match |
Styling Methods (via Styled trait)
Method | Description |
---|---|
text_color(color) | Set text color |
text_size(size) | Set font size |
text_center() | Center align text |
text_right() | Right align text |
font_semibold() | Set font weight to semibold |
font_bold() | Set font weight to bold |
line_height(height) | Set line height |
text_xs() | Extra small text size |
text_sm() | Small text size |
text_base() | Base text size (default) |
text_lg() | Large text size |
text_xl() | Extra large text size |
text_2xl() | 2x large text size |
Examples
Form Labels
rust
// Required field
Label::new("Email Address")
.secondary("*")
.text_color(cx.theme().destructive)
// Optional field
Label::new("Phone Number")
.secondary("(optional)")
// Field with description
Label::new("Password")
.secondary("(minimum 8 characters)")
Search Highlighting
rust
// Interactive search highlighting
let search_term = "Hello";
Label::new("Hello World Hello Universe")
.highlights(search_term) // Highlights all "Hello" occurrences
Sensitive Information
rust
// Financial data with toggle
h_flex()
.child(
Label::new("$9,182.50 USD")
.text_2xl()
.masked(self.is_masked)
)
.child(
Button::new("toggle-mask")
.ghost()
.icon(if self.is_masked { IconName::EyeOff } else { IconName::Eye })
.on_click(|this, _, _, _| {
this.is_masked = !this.is_masked;
})
)
Multi-language Support
rust
// Supports Unicode text
Label::new("这是一个标签") // Chinese text
Label::new("こんにちは世界") // Japanese text
Label::new("🌍 Hello World 🚀") // Emojis
Status Indicators
rust
// Success status
Label::new("✓ Verified")
.text_color(cx.theme().success)
// Warning status
Label::new("⚠ Pending Review")
.text_color(cx.theme().warning)
// Error status
Label::new("✗ Failed")
.text_color(cx.theme().destructive)
Custom Layouts
rust
// Flex layout with labels
h_flex()
.justify_between()
.child(Label::new("Total Amount"))
.child(Label::new("$1,234.56").font_semibold())
// Grid layout
v_flex()
.gap_2()
.child(Label::new("Name:").font_semibold())
.child(Label::new("John Doe"))
.child(Label::new("Email:").font_semibold())
.child(Label::new("john@example.com"))
Accessibility
- Text content is announced by screen readers
- Color alone is not used to convey information (use secondary text for context)
- Sufficient color contrast maintained with theme colors
- Text wrapping ensures content remains readable at different sizes
- Masked content maintains structure for consistent layout
- Highlighting preserves text semantics and readability