Skip to main content

Map styles

React Native SDK provides access to the current map style and style attributes through the styleChannel, map.style, and map.attributes properties, the sublayerAttributes() method of the Map class, and the styleAttributes property of the Style class. Configure the map theme (light or dark) separately using MapAppearance.

Working with styles

The current React Native SDK does not support loading a custom style file. To use a custom style, prepare it at the native level or through the SDK configuration, and manage the available attributes in the React Native code.

Connecting a style to a map​

By default, the map is created with the base SDK style. To apply the style of one map to another, get the current style from the styleChannel property of the source map and assign it to the style property of the target map.

import type { Map } from '@2gis/dgis-mobile-sdk-full';

function copyStyle(sourceMap: Map, targetMap: Map) {
  const style = sourceMap.styleChannel.value;
  targetMap.style = style;
}

Changing a map style​

To change the map appearance without replacing the style, set the attribute values of the map, style, or an individual sublayer. Attribute names must match the conditions and parameters defined in the style.

import { AttributeValue, type Map } from '@2gis/dgis-mobile-sdk-full';

function setNavigatorMode(map: Map, enabled: boolean) {
  map.attributes.setAttributeValue(
    'navigatorOn',
    AttributeValue.boolean(enabled),
  );
}

Switching the theme​

A map style can contain light and dark themes. A MapTheme object describes a specific map theme, while MapAppearance determines how the SDK selects a theme:

  • BySystem contains light and dark themes. The SDK selects one based on the device system theme and automatically switches the map theme when the system settings change.
  • Fixed contains one theme. The map uses it regardless of the device system theme.

In the application system mode, pass the light theme (MapTheme.defaultTheme) in the light parameter of BySystem, and the dark theme (MapTheme.defaultDarkTheme) in the dark parameter.

import { BySystem, MapAppearance, MapTheme } from '@2gis/dgis-mobile-sdk-full';

const mapAppearance = MapAppearance.bySystem(
  new BySystem({
    light: MapTheme.defaultTheme,
    dark: MapTheme.defaultDarkTheme,
  }),
);

If the application stores the selected mode as a string value, convert it to MapAppearance using a shared function:

import {
  BySystem,
  Fixed,
  MapAppearance,
  MapTheme,
} from '@2gis/dgis-mobile-sdk-full';
import type { MapAppearance as SdkMapAppearance } from '@2gis/dgis-mobile-sdk-full';

type MapThemeMode = 'system' | 'light' | 'dark';

function createMapAppearance(mode: MapThemeMode): SdkMapAppearance {
  const lightTheme = MapTheme.defaultTheme;
  const darkTheme = MapTheme.defaultDarkTheme;

  switch (mode) {
    case 'system':
      return MapAppearance.bySystem(
        new BySystem({ light: lightTheme, dark: darkTheme }),
      );
    case 'light':
      return MapAppearance.fixed(new Fixed({ theme: lightTheme }));
    case 'dark':
      return MapAppearance.fixed(new Fixed({ theme: darkTheme }));
  }
}

When creating a map​

To set the initial map theme, pass mapAppearance to MapControllerOptions. The theme is applied when the map is created, including to the background of the MapView loading layer.

import { MapControllerOptions } from '@2gis/dgis-mobile-sdk-full';

const options = new MapControllerOptions({
  mapAppearance: createMapAppearance('system'),
});

After creating a map​

To change the theme after creating the map, assign a new MapAppearance object to the map.appearance property.

import type { Map } from '@2gis/dgis-mobile-sdk-full';

function setSystemTheme(map: Map) {
  map.appearance = createMapAppearance('system');
}

function setLightTheme(map: Map) {
  map.appearance = createMapAppearance('light');
}

function setDarkTheme(map: Map) {
  map.appearance = createMapAppearance('dark');
}

Determining the current theme and mode​

The map.appearance property contains the theme selection rule. To determine the MapAppearance variant, use the mapAppearance.kind property.

For MapAppearanceKind.BySystem, the light and dark themes are available in the mapAppearance.value.light and mapAppearance.value.dark properties. For MapAppearanceKind.Fixed, the selected theme is available in the mapAppearance.value.theme property.

import { MapAppearanceKind } from '@2gis/dgis-mobile-sdk-full';
import type { Color, MapAppearance } from '@2gis/dgis-mobile-sdk-full';
import type { ColorSchemeName } from 'react-native';

function getLoadingBackground(
  mapAppearance: MapAppearance,
  colorScheme: ColorSchemeName,
): Color {
  switch (mapAppearance.kind) {
    case MapAppearanceKind.BySystem:
      return colorScheme === 'dark'
        ? mapAppearance.value.dark.loadingBackground
        : mapAppearance.value.light.loadingBackground;
    case MapAppearanceKind.Fixed:
      return mapAppearance.value.theme.loadingBackground;
  }
}

The current map theme is available in the map.themeChannel. In system mode, MapAppearance.bySystem() contains both themes, while themeChannel returns the specific MapTheme currently used by the SDK.

Managing style layers​

To change the attributes of an individual sublayer, get an Attributes object using the map.sublayerAttributes(name) method. Use this object to set, replace, and remove sublayer attributes.

import { AttributeValue, type Map } from '@2gis/dgis-mobile-sdk-full';

function hideCustomSublayer(map: Map) {
  const attributes = map.sublayerAttributes('custom_objects');

  attributes.setAttributeValues(
    [
      ['visible', AttributeValue.boolean(false)],
      ['opacity', AttributeValue.number(0.35)],
    ],
    [],
  );
}

function resetCustomSublayer(map: Map) {
  map.sublayerAttributes('custom_objects').removeAttribute('visible');
}