Mastering CSS Text Decoration: A Complete Guide

Understanding the text-decoration Shorthand

The text-decoration property in CSS is a shorthand that combines multiple individual properties into a single declaration. According to MDN Web Docs, this shorthand sets the appearance of decorative lines on text, encompassing text-decoration-line, text-decoration-color, text-decoration-style, and the newer text-decoration-thickness property. Understanding this shorthand is essential for writing efficient CSS, but knowing the individual properties gives you much more control over the final result.

When you use the shorthand, you're setting multiple values at once. The most common usage is simply text-decoration: underline, which applies a solid underline in the current text color. However, you can chain values together to create more sophisticated effects. For example, text-decoration: underline overline #ff3028 applies both an underline and an overline in a specific shade of red. The order of values in the shorthand doesn't matter for the appearance, but the shorthand doesn't include every possible text-decoration property, so you'll often need to use individual properties for complete control.

Key Points About the Shorthand

• Basic syntax: The shorthand accepts values for line type, style, color, and thickness in any order
• Common values: underline, overline, line-through, none are the most frequently used line types
• Limitations: The shorthand doesn't include text-underline-offset or text-decoration-skip-ink
• When to use individual properties: For production websites, individual properties provide precise control and integrate better with CSS custom properties in your design system

The shorthand is perfect for quick styling, but for production websites where design consistency and maintainability matter, individual properties often work better. When building websites with modern frameworks, you might define design tokens or CSS variables for each aspect of text decoration, making it easy to maintain consistency across thousands of pages.

Decoration Line Types

Underline Styling

The underline is the most commonly used text decoration, typically indicating links or emphasizing important text. However, default underlines often suffer from poor readability, especially when they intersect with descenders like the tails of g, j, p, q, and y letters. Modern CSS addresses this with text-decoration-skip-ink, which we explore in detail later in this guide.

Default underlines appear very close to the text baseline, which can make them difficult to see clearly. The text-underline-offset property allows you to adjust this distance, creating more visual separation that improves readability without changing the underlying design. For marketing websites where conversions depend on clear call-to-action buttons and links, this small adjustment can have a meaningful impact on user engagement.

When styling underlines for links, consider the overall color scheme of your design. Using a subtle color that contrasts with both the text and the background creates visual hierarchy without creating visual noise. Many modern websites use underlines that are slightly lighter than the text color, or they apply underlines only to specific link states (like hover) to reduce visual clutter in the default state.

Overline and Line-Through

Beyond underlines, CSS supports two additional decoration positions: overline and line-through. The overline creates a line above the text, which is useful for certain typographic effects, highlighting special text, or creating visual distinctions for specific content types. Line-through creates a strikethrough effect, commonly used to indicate deleted text, deprecated features, or discounted prices.

These decoration types work with all the same styling properties as underlines, meaning you can customize their color, style, and thickness just as you would with an underline. For e-commerce websites, line-through is particularly useful when displaying original prices alongside discounted prices, helping users quickly identify savings.

Combining Multiple Decorations

One of the most powerful features of CSS text-decoration is the ability to apply multiple decorations to the same text element. You can specify multiple values for text-decoration-line, and each will be rendered simultaneously:

/* Multiple decorations */
.special-text {
 text-decoration: underline overline line-through red wavy;
}

When combining decorations, each decoration inherits the same color, style, and thickness unless you specify otherwise. The decorations are rendered in the order they appear, with the first decoration appearing closest to the text and subsequent decorations appearing further away. This layering effect can create rich visual effects when used thoughtfully.

Color and Style Customization

Setting Decoration Color

The text-decoration-color property controls the color of decorative lines, and it accepts any valid CSS color value including named colors, hex codes, RGB, RGBA, HSL, and HSLA values. This means you can precisely match your underlines to your brand colors or create contrast that draws attention to specific text elements.

A particularly powerful feature is that text-decoration-color can be animated independently of the text color itself. This opens up possibilities for hover effects, focus states, and animated transitions that make your website feel more interactive and polished. For example, you might animate the underline color from a subtle gray to a vibrant accent color when a user hovers over a link, creating a clear visual feedback mechanism.

When choosing decoration colors, consider the WCAG accessibility guidelines for color contrast. The underline should maintain sufficient contrast against the background to be visible to users with varying visual capabilities. A good rule of thumb is to ensure the decoration color is either darker than the text by at least one shade, or lighter by a noticeable amount, to create clear visual separation.

Line Styles: Solid, Dashed, and Wavy

The text-decoration-style property determines the appearance of the decoration line, offering five distinct options: solid (the default), double, dashed, dotted, and wavy. Each style serves different aesthetic and functional purposes:

• Solid: The most common choice for traditional uses like links
• Double: Adds a more formal, authoritative feel
• Dashed and dotted: Create lighter visual weight for secondary emphasis
• Wavy: Creates a distinctive, hand-drawn aesthetic perfect for highlighting important notes

Controlling Line Thickness

The text-decoration-thickness property, a more recent addition to the CSS specification, gives you precise control over how thick or thin your decoration lines appear. This property accepts absolute lengths (like pixels or em units), percentage values relative to the font size, or the auto keyword.

For high-quality typography, matching decoration thickness to the visual weight of the text is essential. Headlines with bold weights typically benefit from slightly thicker underlines, while light-weight body text often looks best with thinner decorations. When implementing these styles as part of your professional web development services, consistency across all text elements creates a polished, cohesive brand experience.

Modern CSS Text-Decoration Features

text-underline-offset for Visual Refinement

The text-underline-offset property is one of the most impactful additions to the text-decoration toolkit. This property controls the distance between the text and its underline, allowing you to push the line further away from the letters for improved readability or pull it closer for a more compact appearance.

Default underlines often sit too close to the text, which can make them visually cluttered. By adding text-underline-offset: 0.15em, you create breathing room that improves legibility. This adjustment is particularly valuable for longer text passages where users will be reading extensively, as the extra separation reduces eye strain.

The offset can be specified using any length unit, but relative units like em and rem are generally preferred because they scale proportionally with the font size. For responsive designs where text sizes change across breakpoints, using relative units ensures that the underline offset remains visually appropriate at all sizes. When implementing these refinements as part of your modern web development practices, the attention to typography demonstrates professional craftsmanship.

text-decoration-skip-ink for Readability

The text-decoration-skip-ink property addresses one of the most common complaints about default underlines: they cut through descenders in letters like g, j, p, q, and y. When set to auto (the default in most browsers), the underline automatically skips over parts of letters that descend below the baseline:

/* Automatic skip-ink for better readability */
a {
 text-decoration: underline;
 text-decoration-skip-ink: auto;
}

For most use cases, text-decoration-skip-ink: auto is the preferred setting because it maintains better readability across different fonts and text sizes. This property is particularly important when working with decorative or handwritten fonts where descenders can be quite elaborate.

Browser Support

These modern features have excellent support in current browsers. Chrome, Firefox, Safari, and Edge all support text-underline-offset and text-decoration-skip-ink. For older browsers, the underline will still render, just without the enhanced styling. This graceful degradation means you can use these properties today without breaking the experience for users on older browsers.

Performance and Best Practices

CSS Performance Considerations

When building production websites with frameworks like Next.js, CSS performance directly impacts Core Web Vitals metrics that affect both SEO rankings and user experience. Fortunately, text-decoration properties are among the most performant CSS features because they are rendered at the browser's text rendering layer rather than requiring additional DOM elements or complex compositing.

Unlike older techniques that used border-bottom or background-image hacks to create custom underlines, modern text-decoration properties are hardware-accelerated in most browsers. They don't trigger layout recalculations when properties change, and they render consistently across different screen sizes and resolutions. These performance benefits contribute directly to better search engine rankings and improved user satisfaction.

For the best performance, avoid animating text-decoration properties that require layout recalculation. Instead, focus animations on properties that the GPU can handle efficiently, like color transitions for underlines. Use CSS transitions with the GPU-accelerated properties to ensure smooth 60fps animations even on lower-powered devices. By optimizing your CSS in this way, you enhance both user experience and your search engine optimization performance.

Design System Integration

When building scalable websites, integrating text-decoration properties into your design system ensures consistency and maintainability. CSS custom properties (variables) are the ideal tool for this purpose:

:root {
 --link-decoration-color: #2563eb;
 --link-decoration-thickness: 1px;
 --link-underline-offset: 0.15em;
 --link-decoration-skip-ink: auto;
}

a {
 text-decoration-color: var(--link-decoration-color);
 text-decoration-thickness: var(--link-decoration-thickness);
 text-underline-offset: var(--link-underline-offset);
 text-decoration-skip-ink: var(--link-decoration-skip-ink);
}

Accessibility Considerations

Accessibility should be central to any text-decoration implementation. Ensure the decoration doesn't interfere with screen reader output or keyboard navigation, and maintain sufficient color contrast following WCAG guidelines.

When using underlines to indicate links, ensure the color difference between linked and unlinked text meets contrast requirements. Consider users who may have color vision deficiencies by not relying solely on color to convey meaning. Focus states are particularly important for accessibility, ensuring keyboard users receive clear visual feedback when navigating through your site.

Browser Compatibility and Cross-Browser Testing

Modern text-decoration properties have excellent browser support across all major browsers. According to MDN Web Docs, the core text-decoration functionality has been baseline available since July 2015, meaning it's supported in Chrome, Firefox, Safari, and Edge without requiring vendor prefixes or fallback styles.

Browser Support Table

Feature Detection with @supports

For properties like text-decoration-thickness and text-underline-offset, feature detection using @supports allows you to provide graceful degradation:

a {
 /* Fallback for older browsers */
 text-decoration: underline;
}

@supports (text-underline-offset: 4px) {
 a {
 text-underline-offset: 4px;
 text-decoration-thickness: 1px;
 }
}

Testing Strategies

When testing text-decoration across browsers, verify that your styling remains readable at various font sizes and weights. Test with different fonts, including custom web fonts, to ensure descenders render correctly with skip-ink enabled. For responsive web design projects, check how decorations appear on mobile devices where touch targets and visual clarity are especially important.

The progressive enhancement philosophy ensures that all users get a functional, readable experience while users with modern browsers enjoy the enhanced styling. Building websites that work for everyone regardless of their browser choice or device capabilities is a core principle of professional web development.

Sources

1. MDN Web Docs - text-decoration - The authoritative source on CSS specifications, providing technical documentation on all text-decoration properties
2. Theo Soti - Level Up Text Styling with Advanced CSS Underlines - A practical developer-focused guide showcasing modern text-decoration features with code examples