> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/android/navigation/ux/llms.txt)

# UI Configuration

The UX Framework allows for customization of the UI properties using the `DashUiConfig`. Below are the available settings and their respective functionalities.

### `uiModeSettings`

The `uiModeSettings` property controls whether the Dark or Light theme and corresponding map styles should be used in the application.

#### Possible Values

The available values for `uiModeSettings` are defined in the `UiModeSettings` object:

-   `AUTO`: The theme will change automatically at sunrise and sunset.
-   `SYSTEM`: The theme will follow the device's system setting.
-   `DAWN`: The theme will always be dawn.
-   `DAY`: The theme will always be day.
-   `DUSK`: The theme will always be dusk.
-   `NIGHT`: The theme will always be dark.

#### Example Usage

To set the `uiModeSettings` property, configure it within the `Dash.init` method as follows:

```kotlin
Dash.init(
   applicationContext = applicationContext,
   accessToken = getString(R.string.mapbox_access_token)
) {
    ui {
        uiModeSettings = UiModeSettings.DAY
    }
}
```

### `uiModeMapper`

The `UiModeMapper` interface maps the `UiMode` and `UiModeSettings` to a single `UiMode` type. This allows for flexible customization of theme behavior based on different settings.

#### Interface Definition

```kotlin
fun interface UiModeMapper {

    /**
     * Maps the [UiMode] and [UiModeSettings] to a single [UiMode] type.
     */
    suspend fun map(
        @UiMode.Type uiMode: String,
        @UiModeSettings.Type uiModeSettings: String,
    ): @UiMode.Type String
}
```

#### Custom Implementation Example

If you need a custom mapping logic, you can implement the `UiModeMapper` interface as follows:

```kotlin
object CustomUiModeMapper : UiModeMapper {
    override suspend fun map(@UiMode.Type uiMode: String, @UiModeSettings.Type uiModeSettings: String): String {
        return when (uiModeSettings) {
            UiModeSettings.AUTO -> {
                // Custom logic for AUTO setting
                if (isDayTime()) UiMode.LIGHT else UiMode.DARK
            }
            UiModeSettings.SYSTEM -> {
                // Custom logic for SYSTEM setting
                getSystemTheme()
            }
            else -> uiMode
        }
    }

    private fun isDayTime(): Boolean {
        // Determine if it's day or night
        return true // Simplified logic
    }

    private fun getSystemTheme(): String {
        // Get the system theme setting
        return UiMode.LIGHT // Simplified logic
    }

    override fun toString(): String {
        return "CustomUiModeMapper"
    }
}
```

Using this custom mapper in the `Dash.init` method:

```kotlin
Dash.init(
   applicationContext = applicationContext,
   accessToken = getString(R.string.mapbox_access_token)
) {
    ui {
        uiModeMapper = CustomUiModeMapper
    }
}
```

With the `UiModeMapper` interface and its default implementation, you have the flexibility to define how the `UiMode` and `UiModeSettings` are combined to achieve the desired UI theme behavior in your application.

### `streetNameVisibility`

The `streetNameVisibility` property controls the visibility of street names in the application. This allows you to customize when and how street names are displayed based on different modes of the application.

#### Possible Values

The available values for `streetNameVisibility` are defined in the `StreetNameVisibility` object:

-   `OFF`: Street names are disabled.
-   `ALWAYS`: The app displays street names in both Free Drive and Active Guidance modes.
-   `ONLY_FREE_DRIVE`: The app displays street names only in Free Drive mode.
-   `ONLY_ACTIVE_GUIDANCE`: The app displays street names only in Active Guidance mode.

#### Default Value

The default value for `streetNameVisibility` is `StreetNameVisibility.ONLY_ACTIVE_GUIDANCE`.

#### Example Usage

To set the `streetNameVisibility` property, configure it within the `Dash.init` method as follows:

```kotlin
Dash.init(
   applicationContext = applicationContext,
   accessToken = getString(R.string.mapbox_access_token)
) {
    ui {
        streetNameVisibility = StreetNameVisibility.ONLY_FREE_DRIVE
    }
}
```

### `showIncidentsOnRouteLine`

The `showIncidentsOnRouteLine` property controls whether detected incidents should appear on the route line in the application. This allows you to visually display or hide incidents that may affect the route.

#### Default Value

The default value for `showIncidentsOnRouteLine` is `true`, so the route line displays incidents by default.

#### Example Usage

To set the `showIncidentsOnRouteLine` property, configure it within the `Dash.init` method as follows:

```kotlin
Dash.init(
   applicationContext = applicationContext,
   accessToken = getString(R.string.mapbox_access_token)
) {
    ui {
        showIncidentsOnRouteLine = false
    }
}
```

### `showIntersectionsDataOnRouteLine`

The `showIntersectionsDataOnRouteLine` property controls whether intersections data should appear on the route line in the application. This allows you to visually display or hide intersection information along the route.

#### Default Value

The default value for `showIntersectionsDataOnRouteLine` is `true`, so the route line displays intersections data by default.

#### Example Usage

To set the `showIntersectionsDataOnRouteLine` property, configure it within the `Dash.init` method as follows:

```kotlin
Dash.init(
   applicationContext = applicationContext,
   accessToken = getString(R.string.mapbox_access_token)
) {
    ui {
        showIntersectionsDataOnRouteLine = false
    }
}
```

### `mapIncidentsVisibility`

The `mapIncidentsVisibility` property controls the visibility of incidents on the map. This allows you to define when and how incidents are displayed to the user based on different driving modes.

#### Possible Values

The available values for `mapIncidentsVisibility` are defined in the `MapIncidentsVisibility` object:

-   `OFF`: The map does not display incidents.
-   `ALWAYS`: The map displays incidents in both Free Drive and Active Guidance modes.
-   `ONLY_FREE_DRIVE`: The map displays incidents only in Free Drive mode.
-   `ONLY_ACTIVE_GUIDANCE`: The map displays incidents only in Active Guidance mode.

#### Default Value

The default value for `mapIncidentsVisibility` is `MapIncidentsVisibility.ONLY_FREE_DRIVE`.

#### Example Usage

To set the `mapIncidentsVisibility` property, configure it within the `Dash.init` method as follows:

```kotlin
Dash.init(
   applicationContext = applicationContext,
   accessToken = getString(R.string.mapbox_access_token)
) {
    ui {
        mapIncidentsVisibility = MapIncidentsVisibility.ALWAYS
    }
}
```

### `mapTrafficLightsVisibility`

The `mapTrafficLightsVisibility` property controls the visibility of traffic lights on the map. This allows you to define when and how traffic lights are displayed to the user based on different driving modes.

#### Possible Values

The available values for `mapTrafficLightsVisibility` are defined in the `MapTrafficLightsVisibility` object:

-   `NEVER`: Map traffic lights are disabled.
-   `ALWAYS`: Map traffic lights are always visible.
-   `ONLY_FREE_DRIVE`: Map traffic lights are visible only in Free Drive mode.

#### Default Value

The default value for `mapTrafficLightsVisibility` is `MapTrafficLightsVisibility.ONLY_FREE_DRIVE`.

#### Example Usage

To set the `mapTrafficLightsVisibility` property, configure it within the `Dash.init` method as follows:

```kotlin
Dash.init(
   applicationContext = applicationContext,
   accessToken = getString(R.string.mapbox_access_token)
) {
    ui {
        mapTrafficLightsVisibility = MapTrafficLightsVisibility.ALWAYS
    }
}
```

### `mapTrafficVisibility`

The `mapTrafficVisibility` property controls the visibility of traffic information on the map. This allows you to define when and how traffic data is displayed to the user based on different driving modes.

#### Possible Values

The available values for `mapTrafficVisibility` are defined in the `MapTrafficVisibility` object:

-   `NEVER`: Traffic information is disabled on the map.
-   `ALWAYS`: Traffic information is always visible on the map.
-   `ONLY_FREE_DRIVE`: Traffic information is visible only in Free Drive mode.

#### Default Value

The default value for `mapTrafficVisibility` is `MapTrafficVisibility.ONLY_FREE_DRIVE`.

#### Example Usage

To set the `mapTrafficVisibility` property, configure it within the `Dash.init` method as follows:

```kotlin
Dash.init(
   applicationContext = applicationContext,
   accessToken = getString(R.string.mapbox_access_token)
) {
    ui {
        mapTrafficVisibility = MapTrafficVisibility.ALWAYS
    }
}
```

### `screenDirectionality`

The `screenDirectionality` property is used to determine the placement of top level UI components.

#### Possible Values

The available values for `screenDirectionality` are defined in the `ScreenDirectionality` object:

-   `LEFT_TO_RIGHT`: Indicates a left-to-right directionality.
-   `RIGHT_TO_LEFT`: Indicates a right-to-left directionality.

#### Default Value

The default value for `screenDirectionality` is `ScreenDirectionality.LEFT_TO_RIGHT`.

#### Example Usage

To set the `screenDirectionality` property, configure it within the `Dash.init` method as follows:

```kotlin
Dash.init(
   applicationContext = applicationContext,
   accessToken = getString(R.string.mapbox_access_token)
) {
    ui {
        screenDirectionality = ScreenDirectionality.RIGHT_TO_LEFT
    }
}
```

![UX Framework screenshot showing the result of configuring the screen directionality to reflect right-to-left](https://docs.mapbox.com/android/assets/ideal-img/dash-sdk-ui-config-directionality.ecad7f0.480.png)