Docs Editor Model/Schema Cases Scenarios Tips Playground Coverage

CSS & Styling

Understanding CSS properties that affect contenteditable elements, including caret styling, selection styling, focus styles, and browser differences.

Overview

CSS properties can significantly affect contenteditable behavior and appearance. Some properties work well, while others may cause rendering issues, performance problems, or affect selection and caret positioning. Understanding these effects is crucial for creating reliable contenteditable interfaces.

Key Concepts

  • caret-color: Controls the color of the text caret (cursor)
  • user-select: Controls whether and how text can be selected
  • ::selection: Styles the selected text background and color
  • outline/focus-visible: Controls focus indicator styling
  • Transform/Filter: May affect selection handles and caret positioning
  • Performance: Some CSS properties can degrade editing performance

Caret Styling

The caret-color property controls the color of the text caret (cursor) in contenteditable elements. 

// Custom caret color
[contenteditable] {
  caret-color: #0066ff; /* Blue caret */
}

/* Different colors for different states */
[contenteditable]:focus {
  caret-color: #0066ff;
}

[contenteditable]:not(:focus) {
  caret-color: #999; /* Gray when not focused */
}

/* Auto (browser default) */
[contenteditable] {
  caret-color: auto;
}

caret-color Notes

  • Browser Support: Well supported in modern browsers
  • Inheritance: Inherits by default, can be set on contenteditable or parent
  • Auto Value: Uses browser default (usually matches text color)
  • Transparency: Supports transparent and rgba values
  • Dark Mode: Consider different colors for light/dark themes

Text Selection Control

The user-select property controls whether and how text can be selected in contenteditable elements. 

// Control text selection
[contenteditable] {
  user-select: text; /* Allow text selection */
}

/* Prevent selection (not recommended for contenteditable) */
[contenteditable] {
  user-select: none; /* Prevents selection entirely */
}

/* Select all on click */
[contenteditable] {
  user-select: all; /* Selects all text on click */
}

/* Mobile-specific */
[contenteditable] {
  -webkit-user-select: text;
  -webkit-touch-callout: default; /* iOS Safari callout menu */
  user-select: text;
}

⚠️ user-select: none Not Recommended

Setting user-select: none on contenteditable prevents text selection entirely, which breaks essential editing functionality. Users need to select text to delete, copy, or format it. Only use user-select: none on specific non-editable elements within contenteditable, not on the contenteditable itself.

Mobile Considerations

  • -webkit-user-select: Required for iOS Safari
  • -webkit-touch-callout: Controls iOS callout menu (copy, paste, etc.)
  • user-select: all: May cause issues on mobile - selects all text on tap

Selection Styling

The ::selection pseudo-element styles the appearance of selected text. 

// Style selected text
[contenteditable]::selection {
  background: #0066ff;
  color: white;
}

/* For Firefox */
[contenteditable]::-moz-selection {
  background: #0066ff;
  color: white;
}

/* Different styles for different elements */
[contenteditable] strong::selection {
  background: #ff6b35;
  color: white;
}

::selection Notes

  • Firefox: Requires ::-moz-selection prefix
  • Limited Properties: Only color, background-color, text-shadow, and cursor are supported
  • Accessibility: Ensure sufficient contrast between selection background and text color
  • Nested Elements: Can style selection differently for nested elements

Focus Styling

Focus indicators are important for accessibility. Use outline or focus-visible to style focus states. 

// Remove default outline
[contenteditable] {
  outline: none; /* Remove all outlines */
}

/* Custom outline on focus */
[contenteditable]:focus {
  outline: 2px solid #0066ff;
  outline-offset: 2px;
}

/* Use focus-visible for keyboard focus only */
[contenteditable]:focus-visible {
  outline: 2px solid #0066ff;
  outline-offset: 2px;
}

/* Remove outline but keep accessibility */
[contenteditable]:focus {
  outline: none;
  box-shadow: 0 0 0 2px #0066ff;
}

⚠️ Don't Remove Focus Indicators

Removing focus indicators entirely (using outline: none without replacement) harms accessibility. Keyboard users need visible focus indicators. Use focus-visible to show focus only for keyboard navigation, or provide an alternative visual indicator like box-shadow.

Focus Best Practices

  • focus-visible: Shows focus only for keyboard navigation (better UX)
  • outline: Always shows focus (better accessibility)
  • box-shadow: Can be used as alternative to outline
  • Contrast: Ensure focus indicator is clearly visible

Problematic CSS Properties

Some CSS properties can cause issues with contenteditable, affecting selection, caret positioning, rendering, or performance.

transform

CSS transform may cause selection handles and caret to appear in incorrect positions. 

// CSS transform (may affect selection handles)
[contenteditable] {
  transform: scale(0.9);
  /* Selection handles may appear in wrong position */
}

/* Workaround: Use transform on wrapper */
.editor-wrapper {
  transform: scale(0.9);
}

.editor-wrapper [contenteditable] {
  /* No transform on contenteditable itself */
}

⚠️ Selection Handle Misalignment

In Edge on Windows, CSS transforms may cause selection handle misalignment. The caret position may appear offset, and selection handles may not align with selected text. Touch selection on mobile may also be affected. Apply transforms to a wrapper element instead of the contenteditable itself.

filter

CSS filter may degrade editing performance, causing typing lag. 

// CSS filter (may affect performance)
[contenteditable] {
  filter: blur(2px) brightness(1.2);
  /* May cause typing lag */
}

/* Better: Use filter on wrapper or background */
.editor-wrapper {
  filter: blur(2px);
}

.editor-wrapper [contenteditable] {
  filter: none; /* No filter on contenteditable */
}

⚠️ Performance Impact

In Chrome on macOS, CSS filters may cause performance issues. Typing may lag or stutter, and selection updates may be slow. The UI may become unresponsive during rapid editing. Apply filters to wrapper elements or backgrounds instead of the contenteditable itself.

backdrop-filter

CSS backdrop-filter may cause rendering issues, especially on mobile. 

// backdrop-filter (may cause rendering issues)
[contenteditable] {
  backdrop-filter: blur(10px);
  /* May cause text to appear blurry */
}

/* Better: Use on wrapper */
.editor-wrapper {
  backdrop-filter: blur(10px);
}

.editor-wrapper [contenteditable] {
  backdrop-filter: none;
}

⚠️ Rendering Issues

In Safari on iOS, backdrop-filter may cause rendering issues. Text may appear blurry or distorted, selection may not render correctly, and performance may be poor, especially on mobile devices. Avoid using backdrop-filter directly on contenteditable elements.

mix-blend-mode

CSS mix-blend-mode may affect text rendering, selection visibility, and caret rendering. 

// mix-blend-mode (may affect text rendering)
[contenteditable] {
  mix-blend-mode: multiply;
  /* May cause text colors to be incorrect */
  /* Selection may not be visible */
  /* Caret may not render correctly */
}

/* Workaround: Use on wrapper */
.editor-wrapper {
  mix-blend-mode: multiply;
}

.editor-wrapper [contenteditable] {
  mix-blend-mode: normal;
}

⚠️ Text Rendering Issues

In Firefox on Windows, mix-blend-mode may affect text rendering. Text colors may be incorrect, selection may not be visible, and caret may not render correctly. Apply mix-blend-mode to wrapper elements instead of the contenteditable itself.

contain

CSS contain may restrict selection and caret movement. 

// CSS contain (may restrict selection)
[contenteditable] {
  contain: layout style paint;
  /* Selection may not extend beyond boundaries */
  /* Caret movement may be restricted */
}

/* Better: Use contain on parent, not contenteditable */
.editor-container {
  contain: layout style paint;
}

.editor-container [contenteditable] {
  contain: none;
}

⚠️ Selection Restrictions

In Chrome on Windows, CSS contain may restrict selection. Selection may not extend beyond contained boundaries, caret movement may be limited, and selection ranges may be invalidated. Use contain on parent elements, not on the contenteditable itself.

isolation

CSS isolation may affect stacking context and UI element positioning. 

// CSS isolation (may affect stacking context)
[contenteditable] {
  isolation: isolate;
  /* May affect IME candidate window positioning */
  /* Selection handles may be positioned incorrectly */
}

/* Use on wrapper if needed */
.editor-wrapper {
  isolation: isolate;
}

⚠️ Stacking Context Issues

In Safari on macOS, isolation may affect IME candidate window positioning. Selection handles may be positioned incorrectly, z-index stacking may be affected, and overlays may not appear correctly. Use isolation on wrapper elements if needed.

will-change

CSS will-change may improve or degrade performance depending on usage. 

// will-change (may improve or degrade performance)
[contenteditable] {
  will-change: contents;
  /* May improve performance by hinting browser */
  /* Or may degrade performance by creating layers */
}

/* Use specific values */
[contenteditable] {
  will-change: transform; /* If animating */
}

/* Remove when not needed */
[contenteditable]:not(:focus) {
  will-change: auto;
}

will-change Best Practices

  • Use Sparingly: Only when you know an element will change
  • Remove When Done: Set to auto when animation/change is complete
  • Specific Values: Use specific values like transform or contents
  • Memory Impact: May increase memory usage - monitor performance

Platform-Specific Issues & Edge Cases

Browser-Specific Behavior

Chrome/Edge

  • filter: May cause performance issues with typing lag
  • contain: May restrict selection beyond boundaries
  • will-change: Mixed performance effects

Firefox

  • mix-blend-mode: May affect text rendering, selection visibility, and caret
  • ::selection: Requires ::-moz-selection prefix

Safari

  • backdrop-filter: May cause rendering issues, especially on iOS
  • isolation: May affect IME candidate window positioning
  • user-select: Requires -webkit-user-select prefix
  • -webkit-touch-callout: Controls iOS callout menu

OS & Device-Specific Behavior

Desktop

  • Transform: Selection handle misalignment more noticeable
  • Filter: Performance impact more noticeable with rapid typing

Mobile

  • backdrop-filter: More severe rendering issues on mobile
  • user-select: Requires webkit prefixes, touch-callout control
  • Transform: Touch selection may be affected
  • Performance: CSS effects have greater performance impact on mobile

General Edge Cases

  • Combined Properties: Multiple problematic properties together can compound issues
  • Nested Elements: CSS properties on parent elements may affect contenteditable
  • Dynamic Changes: Changing CSS properties dynamically may cause layout shifts
  • Dark Mode: Some properties may behave differently in dark mode
  • High DPI: Rendering issues may be more noticeable on high DPI displays

Best Practices

  • Use caret-color: Customize caret color for better visibility and branding
  • Style Selection: Use ::selection to make selected text clearly visible
  • Maintain Focus Indicators: Always provide visible focus indicators for accessibility
  • Avoid Problematic Properties: Don't apply transform, filter, backdrop-filter, mix-blend-mode directly to contenteditable
  • Use Wrappers: Apply problematic CSS properties to wrapper elements instead
  • Test Performance: Monitor performance when using CSS effects, especially filters
  • Mobile Considerations: Test on mobile devices - CSS effects have greater impact
  • Browser Prefixes: Use appropriate prefixes for cross-browser compatibility
  • Accessibility: Ensure sufficient contrast for selection and focus indicators
  • Dark Mode: Test CSS properties in both light and dark modes

Related Resources