Client Hints

Client hints provide a solution for server-side rendering to respect user preferences without causing content layout shift. This system addresses limitations in server-side rendering where the browser doesn't provide enough information about user preferences.

Key Features

Supported Preferences

• Color scheme (light/dark mode)
• Data saver preferences
• Time zone
• User locale
• Motion preferences
• Cookie preferences

Benefits

• Eliminates flash of incorrect UI
• Provides consistent server-side rendering
• Maintains user preferences across sessions
• Zero content layout shift

How It Works

The system uses cookies to maintain user preferences:

1. First Visit:

   • Quick check for existing preference cookies
   • If not present, loads minimal document
   • Sets cookies with user preferences
   • Reloads page with correct preferences

2. Subsequent Visits:

   • Server reads preferences from cookies
   • Renders content correctly on first load
   • No flash of incorrect content
   • No content layout shift

3. Preference Changes:

   • Monitors for preference changes
   • Updates cookies automatically
   • Triggers reload only if necessary
   • Maintains consistency across sessions

Implementation

Server-Side Usage

import { getHints } from '#app/utils/client-hints'
export async function loader({ request }: LoaderArgs) {
const hints = getHints(request)
// Access user preferences
const theme = hints.theme
const timeZone = hints.timeZone
// ... render with correct preferences
}

Client-Side Usage

import { useHints } from '#app/utils/client-hints'
export function Component() {
const hints = useHints()
// Use preferences in component
const theme = hints.theme
const timeZone = hints.timeZone
// ... render accordingly
}

Cookie Management

Cookie Structure

• Secure, HTTP-only cookies
• Appropriately scoped to domain
• Contains serialized preference data
• Automatically managed by the system

Preference Updates

When user preferences change:

1. System detects the change
2. Updates relevant cookies
3. Triggers minimal reload if necessary
4. Maintains consistency

Fallback Behavior

For users with cookies disabled:

1. System detects cookie limitations
2. Falls back to default values
3. Still functions, but may experience layout shift
4. Degrades gracefully

Best Practices

1. Always use the provided utilities:

   • getHints() for server-side
   • useHints() for client-side

2. Handle preference changes gracefully:

   • Monitor for updates
   • Update UI smoothly
   • Avoid unnecessary reloads

3. Consider fallback values:

   • Define sensible defaults
   • Handle missing preferences
   • Provide graceful degradation

4. Performance considerations:

   • Minimize cookie size
   • Optimize reload triggers
   • Cache preference checks

Security Considerations

The client hints system includes several security measures:

1. Cookie Security:

   • HTTP-only flags
   • Secure flags when appropriate
   • Same-site protection
   • Appropriate cookie scoping

2. Data Validation:

   • Input sanitization
   • Type checking
   • Value validation

3. Privacy Protection:

   • Minimal data collection
   • User control over preferences
   • Clear preference management

Integration with Other Features

Client hints integrate seamlessly with:

1. Theme System

   • Consistent dark/light mode
   • Custom theme preferences
   • System theme detection

2. Localization

   • Time zone handling
   • Locale preferences
   • Number formatting

3. Performance Features

   • Data saver modes
   • Motion preferences
   • Loading optimizations

For more details about security implications, check the security documentation.

Future Enhancements

The system is designed to be future-proof:

1. Web Platform Integration:

   • Ready for native client hints
   • Follows web standards
   • Easy migration path

2. Preference Expansion:

   • Extensible preference system
   • Custom preference support
   • Feature detection

3. Performance Optimization:

   • Reduced reload requirements
   • Better caching strategies
   • Smoother transitions

For implementation details in your deployment, see the deployment documentation.