System Settings
Access user system preferences like time format, calendar settings, and locale.
System Settings
Use the systemSettings module to read preference-like data that the Cosmo app exposes to widgets. These helpers proxy the native SystemSettings Swift API and let you keep all platform-specific logic on the Cosmo side while consuming simple async functions in JavaScript.
Usage
import { systemSettings } from "@buildcosmo/widget";All functions return Promises that resolve after the native bridge replies. They do not require extra permissions because the data comes from the user's local settings and does not identify the user personally.
API Reference
Time & Date Format
is24HourFormat()
Returns true if the user prefers a 24-hour clock (no AM/PM).
const is24h = await systemSettings.is24HourFormat();calendarSystem()
Returns the identifier of the calendar system used by the user (e.g., "gregorian").
const calendar = await systemSettings.calendarSystem();timeZone()
Returns information about the user's current time zone.
const tz = await systemSettings.timeZone();
console.log(tz.identifier); // e.g., "America/Los_Angeles"Returns: Promise<CosmoTimeZone>
type CosmoTimeZone = {
identifier: string; // e.g., "America/Los_Angeles"
abbreviation: string; // e.g., "PDT"
secondsFromGMT: number; // offset in seconds
};Locale & Region
locale()
Returns the user's locale identifier (e.g., "en_US").
const loc = await systemSettings.locale();measurementSystem()
Returns the measurement system used by the locale.
const system = await systemSettings.measurementSystem();
// Returns: 'metric' | 'us' | 'uk'usesMetricSystem()
A convenience boolean to check if the metric system is used.
const isMetric = await systemSettings.usesMetricSystem();Calendar Preferences
firstWeekday()
Returns the index of the first day of the week (1 = Sunday, 2 = Monday, etc.).
const startDay = await systemSettings.firstWeekday();minimumDaysInFirstWeek()
Returns the minimum number of days required in the first week of the year.
const minDays = await systemSettings.minimumDaysInFirstWeek();weekendDays()
Returns an array of weekday indices that are considered weekend days.
const weekends = await systemSettings.weekendDays();
// e.g., [1, 7] for Sunday and SaturdayUsage Examples
Adjusting time formats
const prefers24h = await systemSettings.is24HourFormat();
const timeOptions: Intl.DateTimeFormatOptions = {
hour: "numeric",
minute: "2-digit",
hour12: !prefers24h,
};Toggling measurement units
const system = await systemSettings.measurementSystem();
const distanceUnit = system === "metric" ? "km" : "mi";
const temperatureUnit = system === "us" ? "°F" : "°C";Highlighting weekend days
const weekendDays = await systemSettings.weekendDays();
const weekendSet = new Set(weekendDays);
// Check if today is a weekend
const todayIndex = new Date().getDay() + 1; // 1-based index to match API
if (weekendSet.has(todayIndex)) {
console.log("It's the weekend!");
}System Appearance (Dark Mode)
You can detect the system's light/dark mode using standard Web APIs. No special SDK function is required.
CSS:
@media (prefers-color-scheme: dark) {
body {
background: #000;
color: #fff;
}
}JavaScript:
const isDarkMode = window.matchMedia("(prefers-color-scheme: dark)").matches;
// Listen for changes
window.matchMedia("(prefers-color-scheme: dark)").addEventListener("change", (e) => {
const newColorScheme = e.matches ? "dark" : "light";
console.log(`Theme changed to ${newColorScheme}`);
});