Skip to content

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

MethodDescription
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

VariantDescription
Full(text)Highlights all occurrences of the text
Prefix(text)Highlights only if text appears at the beginning
MethodDescription
as_str()Get the search text as string
is_prefix()Check if this is a prefix match

Styling Methods (via Styled trait)

MethodDescription
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