Settings

The Settings interface provides comprehensive control over application behavior, user preferences, security features, and system configuration.

Overview

Settings are organized into sections accessible through a sidebar navigation (/pages/Settings/SettingsPage.jsx). Each section manages specific aspects of the application:

Home - Quick access to frequently used settings
Security - 2FA, sessions, and activity logs
Appearance - Theme and visual customization
Language & Region - Localization and formatting
Accessibility - Accessibility features
About - System information and version

Architecture

Settings use a context-based architecture with optimistic updates:

const { settings, loading, saveSection, savingMap, reload } = useSettings();

Key Features:

Lazy-loaded sections for performance
Optimistic UI updates with automatic rollback on error
Section-based saves (partial updates)
Real-time synchronization with backend

Security Settings

Two-Factor Authentication (2FA)

Enable 2FA to add an extra layer of account security.

Enable 2FA Toggle

Turn on the Two-Factor Authentication switch

Scan QR Code

A modal opens displaying:

QR code for authenticator apps (Google Authenticator, Authy, etc.)
Manual entry code as backup

Verify Setup

Enter the 6-digit code from your authenticator app to confirm setup

Save Backup Codes

Store backup codes in a secure location for account recovery

2FA Workflow:

// Enrollment initiation
await onSave({ tfa_enroll_init: true });
// Returns: { qr_image: "data:image/png;base64,...", secret: "XXXXX" }

// Verification
await onSave({
  tfa_enroll_verify: true,
  token: "123456",
  secret: setupData.secret
});

Once 2FA is enabled, you’ll need your authenticator app to log in. Keep backup codes safe to avoid account lockout.

Enable email notifications when your account is accessed from a new device:

Send email alerts for new login sessions

When enabled, you receive notifications including:

Device information
IP address
Location (if available)
Timestamp

Active Sessions

View and manage all active login sessions across devices. Session Information Displayed:

Device type (laptop/mobile) with icon
Device name and browser
IP address
Last active timestamp
Current session indicator

Managing Sessions: To revoke all other sessions (except current):

Scroll to Active Sessions section
Click Revoke All Other Sessions button
Confirm the action

This immediately logs out all other devices using:

await revokeOtherSessions();

This feature is useful if you suspect unauthorized access or left yourself logged in on a public computer.

Activity Logs

View recent account activity in a scrollable table:

Column	Description
Action	What was performed (e.g., “Login”, “Password Changed”)
Device	Device information or IP address
Date	When the action occurred

Logs are displayed in reverse chronological order (most recent first). The table shows up to 300px of scrollable content. Loading States:

Skeleton placeholders during data fetch
“No recent activity” message if empty

Appearance Settings

Customize the visual appearance of the application:

theme

select

Choose between Light, Dark, or System (follows OS preference)

colorScheme

select

Primary color scheme for the interface

density

select

UI density: Comfortable, Compact, or Spacious

fontSize

select

Base font size: Small, Medium, or Large

Language & Region Settings

Configure localization and formatting preferences:

language

select

required

Interface language (e.g., “es-HN” for Spanish Honduras, “en-US” for English)

timezone

select

Timezone for timestamp display (default: “America/Tegucigalpa”)

dateFormat

select

Date format:

DD/MM/YYYY (31/12/2023)
MM/DD/YYYY (12/31/2023)
YYYY-MM-DD (2023-12-31)

timeFormat

select

Time format:

12h (3:00 PM)
24h (15:00)

Language Synchronization: When language is changed, the interface updates immediately:

useEffect(() => {
  if (settings?.language && settings.language !== i18n.language) {
    i18n.changeLanguage(settings.language);
  }
}, [settings, i18n]);

No page reload is required.

Accessibility Settings

Enhance usability for users with specific needs:

highContrast

boolean

Enable high contrast mode for better visibility

reduceMotion

boolean

Minimize animations and transitions

Optimize interface for screen readers

Enhanced keyboard navigation support

Settings Context API

The SettingsContext provides a powerful API for managing settings:

Using Settings Context

import { useSettings } from '@/context/SettingsContext';

function MyComponent() {
  const { settings, loading, saveSection, savingMap, reload } = useSettings();
  
  // Access nested settings
  const userTheme = settings?.apariencia?.theme || 'light';
  
  // Save a section
  const handleSave = async () => {
    await saveSection('apariencia', { theme: 'dark' });
  };
}

Context Properties

settings

object

Complete settings object with all sections

boolean

True while initial settings are being loaded

saveSection

function

Function to save a specific settings section:

saveSection(sectionKey: string, partialPayload: object)

savingMap

object

Object tracking save state per section:

{ seguridad: false, apariencia: true }

reload

function

Force reload all settings from server

Saving Settings

Settings are saved using section-based partial updates:

// Save only changed fields in a section
await saveSection('seguridad', {
  tfa_enabled: true,
  login_alerts: false
});

Save Process:

Optimistic Update

UI immediately reflects the change for instant feedback

API Request

PATCH /settings/seguridad with partial payload

Server Response

Backend returns updated section data

Synchronization

Context updates with server data or rolls back on error

Deep Merge Strategy

Settings use a custom deep merge for nested updates:

function deepMerge(target = {}, patch = {}) {
  // Recursively merges patch into target without mutation
  // Handles nested objects while preserving array values
}

This allows partial updates to nested settings:

// Only updates theme, preserves other appearance settings
await saveSection('apariencia', { theme: 'dark' });

Settings Service API

Get All Settings

const settings = await SettingsService.getAllSettings();

Returns complete settings object with all sections.

Get Single Section

const security = await SettingsService.getSection('seguridad');

Returns data for a specific section.

Update Section

const result = await SettingsService.patchSection('seguridad', {
  tfa_enabled: true
});

Performs partial update on a section.

Get Security Data

const { sessions, logs } = await SettingsService.getSecurityData();

Fetches active sessions and activity logs in parallel.

Revoke Sessions

await SettingsService.revokeOtherSessions();

Closes all sessions except the current one.

Section Configuration

Settings sections are lazy-loaded for optimal performance:

const Sections = {
  inicio: React.lazy(() => import('./sections/Inicio.jsx')),
  seguridad: React.lazy(() => import('./sections/Seguridad.jsx')),
  apariencia: React.lazy(() => import('./sections/Apariencia.jsx')),
  idioma: React.lazy(() => import('./sections/IdiomaRegion.jsx')),
  accesibilidad: React.lazy(() => import('./sections/Accesibilidad.jsx')),
  acerca: React.lazy(() => import('./sections/Acerca.jsx')),
};

Preloading on Hover: Sections are preloaded when hovering over navigation items:

onMouseEnter={() => lazyLoaders[item.key]?.()}

This provides instant navigation while keeping initial load small.

Permission Requirements

Some settings require specific permissions:

Setting	Required Permission
Edit any setting	`editar_configuraciones` or Admin role
View settings	All authenticated users

Error Handling

Save Failures

When a save fails:

Optimistic changes are rolled back
Error toast is displayed
Previous state is restored
User can retry the save

Load Failures

If settings fail to load:

Error message is logged to console
Default values are used
User can manually trigger reload

Best Practices

Settings Management Tips

Test Theme Changes: Preview in different lighting conditions
Document Custom Settings: Keep notes on non-default configurations
Regular Backups: Export settings before major changes
Session Management: Revoke sessions periodically for security
Activity Monitoring: Review logs regularly for suspicious activity

Security Best Practices

Enable 2FA for all admin accounts
Review active sessions weekly
Enable login alerts for critical accounts
Use strong, unique passwords
Keep backup codes in a secure location (password manager or safe)
Immediately revoke sessions if device is lost or stolen

Troubleshooting

Settings Not Saving

Check network connection
Verify you have editar_configuraciones permission
Look for error toasts with specific messages
Check browser console for API errors
Try refreshing the page and reapplying changes

2FA Setup Issues

Ensure time is synchronized on your device
Try manual code entry instead of QR scan
Use a compatible authenticator app
Contact support if verification repeatedly fails

Language Not Changing

Verify language pack is available
Clear browser cache
Check if translation files are loaded (console)
Reload the page if change doesn’t apply immediately

Session Revocation Not Working

Verify you’re not trying to revoke the current session
Check if other sessions are actually active
Wait a moment and refresh the sessions list
Verify API endpoint is accessible

User Management - Manage user accounts
Permissions - Configure access control
Locations - Manage geographic data

Get Started

Core Features

User Guides

Administration

Advanced

Overview

Architecture

Security Settings

Two-Factor Authentication (2FA)

Active Sessions

Activity Logs

Appearance Settings

Language & Region Settings

Accessibility Settings

Settings Context API

Using Settings Context

Context Properties

Saving Settings

Deep Merge Strategy

Settings Service API

Get All Settings

Get Single Section

Update Section

Get Security Data

Revoke Sessions

Section Configuration

Permission Requirements

Error Handling

Save Failures

Load Failures

Best Practices

Troubleshooting

Settings Not Saving

2FA Setup Issues

Language Not Changing

Session Revocation Not Working

Build docs developers (and LLMs) love

Get Started

Core Features

User Guides

Administration

Advanced

​Overview

​Architecture

​Security Settings

​Two-Factor Authentication (2FA)

​Login Alerts

​Active Sessions

​Activity Logs

​Appearance Settings

​Language & Region Settings

​Accessibility Settings

​Settings Context API

​Using Settings Context

​Context Properties

​Saving Settings

​Deep Merge Strategy

​Settings Service API

​Get All Settings

​Get Single Section

​Update Section

​Get Security Data

​Revoke Sessions

​Section Configuration

​Permission Requirements

​Error Handling

​Save Failures

​Load Failures

​Best Practices

​Troubleshooting

​Settings Not Saving

​2FA Setup Issues

​Language Not Changing

​Session Revocation Not Working

​Related Pages

Build docs developers (and LLMs) love

Overview

Architecture

Security Settings

Two-Factor Authentication (2FA)

Login Alerts

Active Sessions

Activity Logs

Appearance Settings

Language & Region Settings

Accessibility Settings

Settings Context API

Using Settings Context

Context Properties

Saving Settings

Deep Merge Strategy

Settings Service API

Get All Settings

Get Single Section

Update Section

Get Security Data

Revoke Sessions

Section Configuration

Permission Requirements

Error Handling

Save Failures

Load Failures

Best Practices

Troubleshooting

Settings Not Saving

2FA Setup Issues

Language Not Changing

Session Revocation Not Working

Related Pages