Icon & Badge Slots — leading/trailing icons with automatic color inheritance
Gradient Text — apply gradient effects to entire text or specific words
Prose Mode — optimal typography for long-form articles
Accessibility-First — ARIA role/level added automatically for headings
Basic Usage
The text component accepts positional text, a keyword text: argument, or a block. By default it renders a paragraph element.
Basic Usage
<%=rui_text("Hello World") %><%# as: sets the HTML element %><%=rui_text("Heading", as: :h2, color: :primary) %><%# tag: is an alias for as: — use whichever reads more naturally %><%=rui_text("Heading", tag: :h2, color: :primary) %><%=rui_text(size: :lg, weight: :bold) do%>
Bold large paragraph
<%end%><%# Keyword argument instead of positional %><%=rui_text(text: "Keyword text", as: :span) %>
Hello World
Heading
Bold large paragraph
Keyword text
Headings
Use as: :h1 through as: :h6 for semantic headings. They are responsive (scale up at md: breakpoint) and automatically include role="heading" with aria-level. Prefer tag: if that reads more naturally — it is an alias for as:.
Default paragraph with normal size and weight. Includes bottom margin and proper line height.
Large paragraph with increased font size for emphasis.
Small paragraph, perfect for captions and secondary information.
Inline:
inline: true renders a
span
with no block margin.
Colors
All semantic and Tailwind colors are supported via ColorBuilderHelper, with automatic dark mode.
The brand colors :primary, :secondary, :tertiary and :accent resolve through your app's config.colors, so text follows your palette. Status colors (:success, :danger, :warning, :info) are fixed by convention.
No shade variants — consistent in both light and dark mode.
Black text on light background
Pure black for maximum contrast.
Shade Override (v0.58.0)
Plain text (no variant:) always resolved to a fixed text-{color}-700 light-mode shade. shade: picks a different light-mode step instead, one of the standard Tailwind steps 50 through 950.
Dark mode is not affected by shade:. It stays pinned at the color's existing dark step (300) regardless of the light-mode override — there's no light-to-dark mirroring convention for plain text elsewhere in the library (Tabs' active_shade: leaves its dark tokens untouched too). If you need a specific dark-mode shade, pass it yourself via class:, e.g. class: "dark:text-blue-500".
shade: only reaches plain text — variant: :solid/:outline/:ghost/:soft/:link resolve their color through their own fixed shade table and ignore shade: entirely. nil (the default) keeps the existing 700/300 pair unchanged. An out-of-range value logs a warning and falls back to the default rather than raising.
Sizes
10 sizes from :xs to :xl6 for paragraphs, spans, and divs. Default is :base.
size: does not work on headings
When as: :h1–:h6 is set, the size: param is ignored entirely. Headings use their own fixed responsive scale. See the Headings section for the scale and how to override with class:.
Invalid sizes silently fall back to :base
Only :xs :sm :base :lg :xl :xl2 :xl3 :xl4 :xl5 :xl6 are valid. Anything else (e.g. :xl9, :xl7) resets to :base without an error.
Render semantic blockquotes with a left border and italic style. Add cite: for an attribution footer.
Blockquotes
<%=rui_text(as: :blockquote) do%>
To be or not to be, that is the question.
<%end%><%# With citation %><%=rui_text(as: :blockquote, cite: "William Shakespeare") do%>
The fault, dear Brutus, is not in our stars, but in ourselves.
<%end%><%# Styled blockquote %><%=rui_text(as: :blockquote, cite: "Donald Knuth", color: :primary, font: :serif, size: :lg) do%>
Premature optimization is the root of all evil.
<%end%>
To be or not to be, that is the question.
The fault, dear Brutus, is not in our stars, but in ourselves.
William Shakespeare
Premature optimization is the root of all evil.
Donald Knuth
With Icons
Add icons via the with_icon slot. Icons inherit text color by default. Use position: :leading (default) or :trailing.
With Icons
<%# Leading icon (default) %><%=rui_text("Featured Content", color: :info) do |t| %><% t.with_icon(:star) %><%end%><%# Trailing icon %><%=rui_text("Learn More", color: :primary) do |t| %><% t.with_icon(name: :arrow_right, position: :trailing) %><%end%><%# Icon inside a variant %><%=rui_text("Success!", variant: :solid, color: :success) do |t| %><% t.with_icon(name: :check_circle, position: :leading) %><%end%>
Featured Content
Learn More
Warning Message
Success!
Gradient Text
Apply gradient effects with gradient:. Accepts a style symbol, a matching string, or a hash for word-level targeting.
Gradient Text
<%# Symbol — gradient applied to entire text %><%=rui_text("Beautiful Gradient", gradient: :ocean, size: :xl2, weight: :bold) %><%# String — gradient applied to the matched word only %><%=rui_text("Make it gradient today", gradient: "gradient") %><%# Hash — target a specific word with a specific style %><%=rui_text("Ocean vibes ahead", gradient: { text: "Ocean", style: :ocean }) %>
Sunset Gradient
Ocean Gradient
Forest Gradient
Sunrise Gradient
Aurora Gradient
Available gradient styles:
:sunset — purple → pink (default)
:ocean — yellow → blue → indigo
:forest — blue → teal → green
:sunrise — purple → orange → yellow
:aurora — purple → teal → red
Prose Mode
prose: true adds Tailwind's typography prose classes, giving automatic spacing and styling to raw HTML content inside the element.
Typography is the art and technique of arranging type to make written language legible, readable, and appealing when displayed.
Good typography establishes a strong visual hierarchy, provides a graphic balance to the website, and sets the product's overall tone.
Choose appropriate typefaces
Set proper line heights and spacing
Maintain readability across devices
Text Formatting (rui_text_fmt)
For data-driven text transformations — truncation, highlighting, number formatting, time-ago — use the companion rui_text_fmt component.
TextFmt Features
Truncate — limit text to N characters
Highlight — mark search terms with a colored background
Sanitize — strip dangerous HTML
Number Formatting — currency, percentage, phone numbers
Time Ago — "3 hours ago" format
Linkify — auto-convert URLs to links
Pluralize — "1 item" vs "5 items"
Text Formatting Examples
<%=rui_text_fmt("This is a very long text...", truncate: 30) %><%=rui_text_fmt(99.99, number_format: :currency) %><%=rui_text_fmt("Search for Rails in this text", highlight: "Rails") %><%=rui_text_fmt(Time.now - 2.hours, time_ago: true) %><%=rui_text_fmt("comment", pluralize: true, count: 5, variant: :soft, color: :info) %>
This is a very long text that will be truncated...
$99.99
Search for Rails in this Rails text
5 comments
API Reference
rui_text
Typography component for semantic, accessible text with full styling control.
Parameter
Type
Default
Description
content
String
—
Text content — positional first arg, keyword text:, or block
as
Symbol
:p
HTML element to render. Headings (h1–h6) are responsive and get ARIA role/level automatically.
Line height. Alias for line_height:. For headings, only takes effect when explicitly set.
:none:tight:snug:normal:relaxed:loose
line_height
Symbol
:normal
Line height (prefer the leading: alias). Options same as leading:.
:none:tight:snug:normal:relaxed:loose
tracking
Symbol
:normal
Letter spacing. Alias for letter_spacing:.
:tighter:tight:normal:wide:wider:widest
letter_spacing
Symbol
:normal
Letter spacing (prefer the tracking: alias). Options same as tracking:.
:tighter:tight:normal:wide:wider:widest
Color
Text color and gradient effects via ColorBuilderHelper.
Parameter
Type
Default
Description
color
Symbol
:primary
Text color. Accepts any semantic color (:primary, :success, :danger, :warning, :info) or any Tailwind palette color (:red, :blue, :emerald, etc.).
shade
Integer
—
Plain/default-variant text only (v0.58.0+) — overrides the fixed light-mode 700 shade with a standard Tailwind step. nil keeps 700 unchanged; an out-of-range value warns and falls back to nil. Dark mode stays pinned at the color's existing 300 regardless of shade: — pass class: for a specific dark shade. Ignored when variant: is :solid/:outline/:ghost/:soft/:link.
50100200300400500600700800900950
gradient
Symbol / String / Hash
—
Gradient effect. Symbol applies to entire text; String matches a word; Hash { text:, style: } targets a specific word with a specific style.
:sunset:ocean:forest:sunrise:aurora
accent
Boolean
false
Apply opacity-80 for a subtly dimmed appearance — useful for secondary text in a colored context.
Formatting
Text alignment, transform, decoration, and italic.
Parameter
Type
Default
Description
align
Symbol
:left
Text alignment. No CSS class is emitted for the default :left.
:left:center:right:justify
transform
Symbol
—
CSS text-transform.
:uppercase:lowercase:capitalize:normal
decoration
Symbol
—
CSS text-decoration. Use :line_through (underscore) not :line-through.
:underline:overline:line_through:none
italic
Boolean
false
Apply CSS font-style: italic (adds the italic Tailwind class).
Variants
Visual styling presets. Colored variants (solid/outline/ghost/soft/link) require a color: value.
Parameter
Type
Default
Description
variant
Symbol
:default
Visual style. :solid, :outline, :ghost, :soft, :link use ColorBuilderHelper with the color: value. :strong adds font-bold. :subtle adds opacity-70.
Apply Tailwind Typography prose classes for long-form content. When true, most other styling params are bypassed.
cite
String
—
Blockquote citation. Only used when as: :blockquote. Renders a <cite> element below the quote with an aria-describedby link.
Slots
Content slots for customizing component parts
Slot
Description
with_icon
Icon slot. Accepts name: (Lucide icon symbol) and position: (:leading or :trailing, default :leading). Icon inherits text color unless color: is explicitly set on the icon.
with_badge
Badge slot. Appends a Badge component after the text content.