Platform

Android

Language

Kotlin

Configure Navigation Bar

In this example, we will show you how to make navigation bar configurations for the mobile editor. The example is based on the Design Editor, however, it is exactly the same for all the other solutions.

Explore a full code sample on GitHub.

View on GitHub

NavigationBar is a list of items placed horizontally at the top of the editor. It has type NavigationBar : EditorComponent and every item in the navigation bar has type NavigationBar.Item : EditorComponent. NavigationBar.Item is an abstract class that currently has two implementations: NavigationBar.Button and NavigationBar.Custom. NavigationBar.Button is an editor component that has an icon and a text positioned in a column, while NavigationBar.Custom is a fully custom editor component that allows drawing arbitrary content. Prefer using NavigationBar.Custom for rendering custom content in the navigation bar over inheriting from NavigationBar.Item.

NavigationBar is part of the EditorConfiguration, therefore, in order to configure the navigation bar we need to configure the EditorConfiguration. Below you can find the list of available configurations of the navigation bar. To demonstrate the default values, all parameters are assigned to their default values. Consider using NavigationBar.rememberFor{solution_name} helper functions when providing a navigation bar for a specific solution.

scope - the scope of this component. Every new value will trigger recomposition of all the lambda parameters below. If you need to access EditorScope to construct the scope, use LocalEditorScope. Consider using Compose State objects in the lambda parameters below for granular recompositions over updating the scope, since scope change triggers full recomposition of the navigation bar. Prefer updating individual NavigationBar.Items over updating the whole navigation bar. Ideally, scope should be updated when the parent scope (scope of the parent component) is updated and when you want to observe changes from the Engine. By default the scope is updated only when the parent scope (accessed via LocalEditorScope) is updated.

visible - whether the navigation bar should be visible. Default value is always true.

enterTransition - transition of the navigation bar when it enters the parent composable. Default value is always no enter transition.

exitTransition - transition of the navigation bar when it exits the parent composable. Default value is always no exit transition.

decoration - decoration of the navigation bar. Useful when you want to add custom background, foreground, shadow, paddings etc. By default decoration adds background color and applies paddings to the navigation bar.

listBuilder - a builder that registers the list of NavigationBar.Items that should be part of the navigation bar. Note that registering does not mean displaying. The items will be displayed if NavigationBar.Item.visible is true for them. By default listBuilder does not add anything to the navigation bar. For configuration details, see ListBuilder Configuration section.

horizontalArrangement - the horizontal arrangement that should be used to render the items in the navigation bar horizontally. Default value is Arrangement.SpaceEvenly.

itemDecoration - decoration of the items in the navigation bar. Useful when you want to add custom background, foreground, shadow, paddings etc to the items. Prefer using this decoration when you want to apply the same decoration to all the items, otherwise set decoration to individual items. Default value is always no decoration.

NavigationBar.ListBuilder Configuration#

There are two main ways to create an instance of NavigationBar.ListBuilder. First way is to call modify on an existing builder, and the second way is to create the builder from scratch. Currently, there are three available builders:

NavigationBar.ListBuilder.rememberForDesign() that is recommended to be used in Design Editor.

NavigationBar.ListBuilder.rememberForPhoto() that is recommended to be used in Photo Editor.

NavigationBar.ListBuilder.rememberForVideo() that is recommended to be used in Video Editor.

NavigationBar.ListBuilder.rememberForApparel() that is recommended to be used in Apparel Editor.

NavigationBar.ListBuilder.rememberForPostcard() that is recommended to be used in Postcard Editor.

Modifying an Existing Builder#

In this example, we will modify NavigationBar.ListBuilder.rememberForDesign. Modifying builders can be used, when you do not want to touch the default general order of the items in the builder, but rather add additional items and replace/hide some of the default items. To achieve that, there are multiple available functions in the scope of modify lambda:

addFirst - prepends a new NavigationBar.Item in the list. Note that the parameter alignment is mandatory in case the original ListBuilder contains aligned items in order to indicate which aligned group the new item belongs to. In this example, the orginal ListBuilder contains aligned items. More about aligned items can be found in the next section.

addLast - appends a new NavigationBar.Item in the list. Note that the parameter alignment is mandatory in case the original ListBuilder contains aligned items in order to indicate which aligned group the new item belongs to. In this example, the orginal ListBuilder contains aligned items. More about aligned items can be found in the next section.

addAfter - adds a new NavigationBar.Item right after the item with provided id. An exception will be thrown if no item exists with provided id in the default builder.

addBefore - adds a new NavigationBar.Item right before the item with provided id. An exception will be thrown if no item exists with provided id in the default builder.

replace - replaces the NavigationBar.Item with provided id. An exception will be thrown if no item exists with provided id in the default builder. Also note that the new item does not need to have the same id.

remove - removes the NavigationBar.Item with provided id. An exception will be thrown if no item exists with provided id in the default builder.

Warning#

Note that the order of items may change between editor versions, therefore ListBuilder.modify must be used with care. Consider creating a new builder if you want to have strict ordering between different editor versions.

Creating a New Builder#

In this example, we will create a builder from scratch that will be used in the NavigationBar of DesignEditor solution. Creating a new builder is recommended, when you want to touch the default order of available builders, as well as when available builders do not contain the items that you want. This example mimics reordering the default order of items in NavigationBar.ListBuilder.rememberForDesign builder. In addition, some items are removed and a new custom item is added in a new aligned group.

As you can see, all the items are part of aligned groups positioned in different horizontal locations, however it is possible to add all the items outside aligned functions and control their horziontal arrangement via horizontalArrangement (see NavigationBar Configuration section). See analogous documentation of Dock and InspectorBar for reference of non-aligned items.

Warning#

It is not allowed to add items both inside and outside align blocks at the same time: either all items should be in aligned groups, or no items at all.

NavigationBar.Item Configuration#

As mentioned in the Navigation Bar Architecture section, NavigationBar.Item is an EditorComponent and it has two subtypes: NavigationBar.Button and NavigationBar.Custom.

NavigationBar.Button Configuration#

In order to create a navigation bar button, use NavigationBar.Button.remember composable function. Below you can find the list of available configurations when creating a NavigationBar.Button. To demonstrate the default values, all parameters are assigned to their default values whenever possible.

id - the id of the button. Note that it is highly recommended that every unique EditorComponent has a unique id. Parameter does not have a default value.

scope - the scope of this component. Every new value will trigger recomposition of all the lambda parameters below. If you need to access EditorScope to construct the scope, use LocalEditorScope. Consider using Compose State objects in the lambda parameters below for granular recompositions over updating the scope, since scope change triggers full recomposition of the button. Ideally, scope should be updated when the parent scope (scope of the parent component NavigationBar - NavigationBar.Scope) is updated and when you want to observe changes from the Engine. By default the scope is updated only when the parent component scope (NavigationBar.scope, accessed via LocalEditorScope) is updated.

visible - whether the button should be visible. Default value is always true.

enterTransition - transition of the button when it enters the parent composable. Default value is always no enter transition.

exitTransition - transition of the button when it exits the parent composable. Default value is always no exit transition.

decoration - decoration of the button. Useful when you want to add custom background, foreground, shadow, paddings etc. Default value is always no decoration.

onClick - the callback that is invoked when the button is clicked. Parameter does not have a default value.

icon - the icon content of the button. If null, it will not be rendered. Default value is null.

text - the text content of the button. If null, it will not be rendered. Default value is null.

enabled - whether the button is enabled. Default value is always true.

Other than the main NavigationBar.Button.remember function, there is one more convenience overload that has three differences:

icon is replaced with vectorIcon lambda, that returns VectorIcon instead of drawing the icon content.
text is replaced with text lambda, that returns String instead of drawing the text content.
An extra parameter contentDescription is added that is used by accessibility services to describe what the button does. Note that it is not required to provide value when text is not null, since its value will be used by accessibility services, however having both text and contentDescription as null will cause a crash.

NavigationBar.Custom Configuration#

In order to create a custom navigation bar item, use NavigationBar.Custom.remember composable function. Below you can find the list of available configurations when creating a NavigationBar.Custom item. To demonstrate the default values, all parameters are assigned to their default values whenever possible.

id - the id of the custom item. Note that it is highly recommended that every unique EditorComponent has a unique id. Parameter does not have a default value.

scope - the scope of this component. Every new value will trigger recomposition of all the lambda parameters below. If you need to access EditorScope to construct the scope, use LocalEditorScope. Consider using Compose State objects in the lambda parameters below for granular recompositions over updating the scope, since scope change triggers full recomposition of the custom item. Ideally, scope should be updated when the parent scope (scope of the parent component NavigationBar - NavigationBar.Scope) is updated and when you want to observe changes from the Engine. Parameter does not have a default value.

visible - whether the custom item should be visible. Default value is always true.

enterTransition - transition of the custom item when it enters the parent composable. Default value is always no enter transition.

exitTransition - transition of the custom item when it exits the parent composable. Default value is always no exit transition.

content - the content of the custom item. You are responsible for drawing it, handling clicks etc. Parameter does not have a default value.


import androidx.compose.animation.EnterTransition
import androidx.compose.animation.ExitTransition
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.heightIn
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.navigation.NavHostController
import ly.img.editor.DesignEditor
import ly.img.editor.EditorConfiguration
import ly.img.editor.EngineConfiguration
import ly.img.editor.core.LocalEditorScope
import ly.img.editor.core.component.NavigationBar
import ly.img.editor.rememberForDesign

// Add this composable to your NavHost
@Composable
fun SimpleNavigationBarSolution(navController: NavHostController) {
    val engineConfiguration = EngineConfiguration.rememberForDesign(
        license = "<your license here>",
    )
    val editorConfiguration = EditorConfiguration.rememberForDesign(
        navigationBar = {
            NavigationBar.remember(
                scope = LocalEditorScope.current.run {
                    remember(this) { NavigationBar.Scope(parentScope = this) }
                },
                visible = { true },
                enterTransition = { EnterTransition.None },
                exitTransition = { ExitTransition.None },
                decoration = {
                    // Also available via NavigationBar.DefaultDecoration
                    Box(
                        modifier =
                            Modifier
                                .fillMaxWidth()
                                .heightIn(min = 64.dp)
                                .background(MaterialTheme.colorScheme.surface)
                                .padding(PaddingValues(horizontal = 4.dp)),
                        contentAlignment = Alignment.Center,
                    ) {
                        it()
                    }
                },
                listBuilder = NavigationBar.ListBuilder.remember { },
                horizontalArrangement = { Arrangement.SpaceEvenly },
                // default value is { it() }
                itemDecoration = {
                    Box(modifier = Modifier.padding(2.dp)) {
                        it()
                    }
                },
            )
        },
    )
    DesignEditor(
        engineConfiguration = engineConfiguration,
        editorConfiguration = editorConfiguration,
    ) {
        // You can set result here
        navController.popBackStack()
    }
}

List of Available NavigationBar.Buttons#

As you often saw in the previous sections, there are composable functions that look like this: NavigationBar.Button.remember{name}. All these functions return a NavigationBar.Button, they are public and can be used in your application. Note that all the parameters of these functions have default values, therefore, you do not need to provide any values, however, if you want to modify any of the parameters, it is exactly the same as described in NavigationBar.Button Configuration section.

Button	Id	Description
Button `NavigationBar.Button.rememberCloseEditor`	Id `NavigationBar.Button.Id.closeEditor`	Description Triggers EngineConfiguration.onClose callback via `EditorEvent.OnClose`.
Button `NavigationBar.Button.rememberUndo`	Id `NavigationBar.Button.Id.undo`	Description Does undo operation in the editor via EditorApi.undo engine API.
Button `NavigationBar.Button.rememberRedo`	Id `NavigationBar.Button.Id.redo`	Description Does redo operation in the editor via EditorApi.redo engine API.
Button `NavigationBar.Button.rememberExport`	Id `NavigationBar.Button.Id.export`	Description Triggers EngineConfiguration.onExport callback via `EditorEvent.Export`.
Button `NavigationBar.Button.rememberTogglePreviewMode`	Id `NavigationBar.Button.Id.togglePreviewMode`	Description Updates editor view mode via `EditorEvent.SetViewMode`: when current view mode is `EditorViewMode.Edit`, then `EditorViewMode.Preview` is set and vice versa. Note that this button is intended to be used in Photo Editor, Apparel Editor and Postcard Editor and may cause unexpected behaviors when used in other solutions.
Button `NavigationBar.Button.rememberTogglePagesMode`	Id `NavigationBar.Button.Id.togglePagesMode`	Description Updates editor view mode via `EditorEvent.SetViewMode`: when current view mode is `EditorViewMode.Edit`, then `EditorViewMode.Pages` is set and vice versa. Note that this button is intended to be used in Design Editor and may cause unexpected behaviors when used in other solutions.
Button `NavigationBar.Button.rememberPreviousPage`	Id `NavigationBar.Button.Id.previousPage`	Description Navigates to the previous page via `EditorEvent.Navigation.ToPreviousPage`.
Button `NavigationBar.Button.rememberNextPage`	Id `NavigationBar.Button.Id.nextPage`	Description Navigates to the next page via `EditorEvent.Navigation.ToNextPage`.

Configure Navigation Bar

Navigation Bar Architecture#

Navigation Bar Configuration#

NavigationBar.ListBuilder Configuration#

Modifying an Existing Builder#

Warning#

Creating a New Builder#

Warning#

NavigationBar.Item Configuration#

NavigationBar.Button Configuration#

NavigationBar.Custom Configuration#

List of Available NavigationBar.Buttons#