Description

The JavaScript String method toLocaleUpperCase() returns the given string in uppercase according to the current locale, without changing the original string.

  • The locale is determined based on the language setting of the browser.
  • It returns a new string and doesn't change the original string.
  • It is commonly used to convert a text to its uppercase considering the current locale.

This method returns the same result as the method toUpperCase() except for the locales that conflict with the regular Unicode case mapping, such as Turkish.

Syntax

The method toLocaleUpperCase() has the below syntax, where str is a string.

str.toLocaleUpperCase()

Parameters

The method toLocaleUpperCase() doesn't allow any parameters.

Result

Returns the uppercase representation of a string according to the current locale, without changing the original string.

Returns TypeError for null and undefined values.

Example 1: Using the Method

The below example shows the basic usage of the method.

var str1 = "Hello World!";
var str2 = "HELLO WORLD!";
var str3 = "hello world!";

document.write(str1.toLocaleUpperCase());    // Prints: HELLO WORLD!
document.write(str2.toLocaleUpperCase());    // Prints: HELLO WORLD!
document.write(str3.toLocaleUpperCase());    // Prints: HELLO WORLD!

Output:

HELLO WORLD!
HELLO WORLD!
HELLO WORLD!

Example 2: Method Returns TypeError

The method returns TypeError for null and undefined values.

var str1;           // This variable contains undefined
var str2 = null;    // This variable contains null

// Returns TypeError
document.write(str1.toLocaleUpperCase());    // Returns TypeError
document.write(str2.toLocaleUpperCase());    // Returns TypeError

Output:

TypeError: Cannot read properties of undefined (reading 'toUpperCase')
TypeError: Cannot read properties of null (reading 'toUpperCase')

Overall

The JavaScript String method toLocaleUpperCase() returns the given string in uppercase according to the current locale, without changing the original string.

Related Links