Intl.supportedValuesOf()

What Is Intl.supportedValuesOf()?

The Intl.supportedValuesOf() static method returns an array containing the supported calendar, collation, currency, numbering system, time zone, or unit values supported by the JavaScript implementation. This API is essential for building flexible, locale-aware applications that gracefully handle varying levels of internationalization support.

Key capabilities:

• Feature detection for internationalization support
• Dynamic discovery of available calendar types
• Currency and unit formatting options
• Time zone and numbering system discovery

As global audiences increasingly expect personalized digital experiences, the ability to programmatically discover what internationalization features are available becomes critical for web development teams building applications that serve users worldwide. The ECMAScript Internationalization API specification, maintained by TC39, introduced this capability to enable developers to create truly adaptive solutions that work across different browser environments and runtime configurations.

The API achieved Baseline status in March 2022, meaning it works consistently across Chrome, Edge, Firefox, and Safari, making it safe for production use without polyfill concerns for the vast majority of users. This standardization enables progressive enhancement strategies where applications can load internationalization polyfills only when necessary, reducing bundle sizes and improving initial page load performance for users who don't need advanced localization features.

For businesses targeting international markets, proper implementation of these APIs supports international SEO efforts by ensuring search engines can properly parse and index localized content across different date formats, number conventions, and regional preferences.

Working with Calendar Types

The calendar support reveals diverse calendar systems used globally. Modern applications need multiple calendar support to serve international audiences effectively, whether displaying dates for users in Japan who prefer the imperial era system, users in Middle Eastern countries who use Islamic calendars, or users in East Asian regions who follow traditional lunisolar systems.

Common Calendar Types

• gregory - International standard Gregorian calendar
• japanese - Japanese Imperial calendar with eras
• islamic-umalqura - Islamic calendar (Umm al-Qura, Saudi Arabia)
• chinese - Traditional Chinese lunisolar calendar
• hebrew - Traditional Hebrew calendar
• buddhist - Thai Buddhist calendar

Practical Example

// Get supported calendars
const calendars = Intl.supportedValuesOf("calendar");

// Format date using Japanese calendar
const jpFormatter = new Intl.DateTimeFormat("ja-JP", {
 calendar: "japanese",
 year: "numeric",
 month: "long",
 day: "numeric",
 era: "long"
});

console.log(jpFormatter.format(new Date()));
// "2025年1月9日 令和7年"

Best Practices for Calendar Selection

When implementing calendar support in your application, always validate whether a calendar is supported before attempting to use it. Store user calendar preferences persistently and apply them consistently across all date formatting operations. Consider presenting calendar options with both technical identifiers and human-readable descriptions to improve usability. For financial or scheduling applications serving diverse regions, implement fallback mechanisms that default to the Gregorian calendar when a user's preferred system isn't available, ensuring the application remains functional regardless of the user's locale settings.

Time Zone Discovery

The Intl.supportedValuesOf("timeZone") method returns IANA time zone identifiers for displaying times across global locations accurately. For applications that schedule meetings across time zones, display international shipping estimates, or simply show users the current time in different locations, this capability ensures accurate and consistent date/time formatting.

Common Time Zone Operations

• Discovering available time zones dynamically
• Formatting dates for specific geographic locations
• Building time zone selection dropdowns
• Handling daylight saving time transitions automatically

Organizing Large Time Zone Lists

The list of supported time zones can be extensive, with hundreds of entries representing cities and regions worldwide. When building user interfaces for time zone selection, organize the list hierarchically by continent/region to make navigation manageable. Extract unique regions from time zone strings using split("/")[0] to create a navigable category structure. For improved user experience, highlight the user's current time zone as the default selection and provide search functionality for quick access to commonly used time zones.

The relationship between time zones and locale preferences is significant but distinct--while a user's locale may suggest a default time zone, they often need independent control over each setting. International travelers may prefer seeing times in their home time zone while browsing in a local language, while expatriates may want local time displayed while keeping their interface in their native language. Building flexible timezone handling into your web applications from the start ensures these use cases are supported without architectural changes later.

Best Practices

Feature Detection

Use Intl.supportedValuesOf() for feature detection to enable progressive enhancement. This approach supports applications that need to work across different browser capabilities while providing enhanced features when supported:

function isCalendarSupported(calendar) {
 return Intl.supportedValuesOf("calendar").includes(calendar);
}

function isUnitSupported(unit) {
 return Intl.supportedValuesOf("unit").includes(unit);
}

Performance Optimization

Cache supported values at module level to avoid repeated calls. The values don't change during runtime, so computing them once and reusing the results improves performance significantly:

// Cache at module load
const SUPPORTED_CALENDARS = Object.freeze(Intl.supportedValuesOf("calendar"));
const SUPPORTED_UNITS = Object.freeze(Intl.supportedValuesOf("unit"));
const SUPPORTED_CURRENCIES = Object.freeze(Intl.supportedValuesOf("currency"));

Error Handling

The method throws RangeError for invalid keys, so proper error handling is essential:

function safelyGetSupportedValues(key) {
 const validKeys = ["calendar", "collation", "currency", 
 "numberingSystem", "timeZone", "unit"];
 
 if (!validKeys.includes(key)) {
 throw new RangeError(`Invalid key: "${key}"`);
 }
 
 try {
 return Intl.supportedValuesOf(key);
 } catch (error) {
 console.error("Failed to get supported values:", error);
 return [];
 }
}

Browser Compatibility

The API is widely available (Baseline since March 2022) across Chrome, Edge, Firefox, Safari, and Node.js 18+. For older browser environments, implement feature detection and provide fallback values for commonly used options.

Organizations looking to implement comprehensive internationalization across their digital properties can benefit from our AI automation services which can help manage localization workflows and content translation at scale.

Integration with Next.js

When using Intl.supportedValuesOf() in Next.js applications, values are determined by the Node.js runtime environment rather than the browser. This distinction is important for applications that need to present identical options to all users regardless of their browser--server-side determination ensures consistency across the user base.

Server-Side vs Client-Side Considerations

For optimal performance in Next.js applications, compute supported values on the server and cache them for reuse across requests. Use React's cache() function to memoize these computations and prevent redundant work. In client components, detect feature availability before attempting to use the API, providing graceful fallbacks for environments where it isn't supported.

React Hook Implementation

Creating a custom hook encapsulates internationalization logic and improves code organization:

import { useMemo } from 'react';

export function useIntlSupport() {
 return useMemo(() => {
 if (typeof Intl === "undefined" || !Intl.supportedValuesOf) {
 return null;
 }
 
 return {
 calendars: Intl.supportedValuesOf("calendar"),
 units: Intl.supportedValuesOf("unit"),
 currencies: Intl.supportedValuesOf("currency"),
 timeZones: Intl.supportedValuesOf("timeZone"),
 numberingSystems: Intl.supportedValuesOf("numberingSystem")
 };
 }, []);
}

For React applications built with Next.js, this hook pattern provides clean separation of concerns while ensuring internationalization features are discovered efficiently. Server components can pre-compute supported values and pass them as props, while client components can use the hook to access this data without duplicating work.

Conclusion

The Intl.supportedValuesOf() API provides essential capabilities for building globally-aware JavaScript applications. By enabling programmatic discovery of supported internationalization features, it empowers developers to create adaptive experiences that serve users worldwide with consistent, culturally appropriate formatting.

Key takeaways:

1. Feature Detection: Use it to determine available internationalization capabilities before attempting to use specific features
2. Dynamic UIs: Build user interfaces that adapt to actual browser and runtime capabilities rather than hardcoded assumptions
3. Progressive Enhancement: Load polyfills only when necessary, reducing bundle size and improving performance
4. Performance: Cache results at module level and avoid repeated method calls
5. Error Handling: Validate keys and handle RangeError exceptions gracefully

With broad browser support since March 2022 and availability in Node.js 18+, Intl.supportedValuesOf() is ready for production use in modern web applications. Whether you're building e-commerce platforms that need robust currency formatting, scheduling applications that must handle multiple calendar systems, or any application serving international audiences, this API provides the foundation for truly global JavaScript implementations.

Sources

1. MDN Web Docs - Intl.supportedValuesOf() - Comprehensive official documentation covering syntax, parameters, return values, and browser compatibility
2. MDN Web Docs - Intl.NumberFormat - Number formatting options including unit and currency styling
3. Raymond Camden - Unit Formatting with Intl in JavaScript - Practical developer tutorial demonstrating unit formatting use cases
4. TC39 ECMAScript Internationalization API Specification - Official ECMAScript standard defining the Internationalization API specification