Skip to main content

Use locally generated ideographs

Rendering Chinese/Japanese/Korean (CJK) ideographs and precomposed Hangul Syllables requires downloading large amounts of font data, which can significantly slow map load times. Use the localIdeographFontFamily setting to speed up map load times by using locally available fonts instead of font data fetched from the server. This setting defines a CSS 'font-family' for locally overriding generation of glyphs in the 'CJK Unified Ideographs' and 'Hangul Syllables' Unicode ranges. In these ranges, font settings from the map's style will be ignored in favor of the locally available font, while the non-CJK text will use the font specified in the map's style. If the font specified in localIdeographFontFamily does not exist in Mapbox Studio, specifying this font in the style layer can cause the text to not load.

Keywords in the fontstack defined in the map's style (light, regular, medium, and bold) will be translated into a CSS 'font-weight'. For more details, see the localIdeographFontFamily option for Map.

This setting is enabled by default to use the system 'sans-serif' font. When overriding this setting, the fonts you select may not be available on all users' devices. Specify at least one broadly available fallback font class such as 'sans-serif'. Note that Mapbox Studio sets this value to false by default.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Use locally generated ideographs</title>
<meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no">
<link href="https://api.mapbox.com/mapbox-gl-js/v3.2.0/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v3.2.0/mapbox-gl.js"></script>
<style>
body { margin: 0; padding: 0; }
#map { position: absolute; top: 0; bottom: 0; width: 100%; }
</style>
</head>
<body>
<div id="map"></div>

<script>
// TO MAKE THE MAP APPEAR YOU MUST
// ADD YOUR ACCESS TOKEN FROM
// https://account.mapbox.com
mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';
const map = new mapboxgl.Map({
container: 'map',
// Choose from Mapbox's core styles, or make your own style with Mapbox Studio
style: 'mapbox://styles/mapbox/streets-v12',
center: [120.3049, 31.4751],
zoom: 12,
localIdeographFontFamily: "'Noto Sans', 'Noto Sans CJK SC', sans-serif"
});
</script>

</body>
</html>
Was this example helpful?