TopAppBar

TopAppBar is a top application bar component in Miuix, used to provide navigation, title, and action buttons at the top of the interface. It supports both large title and regular modes, as well as dynamic effects during scrolling.

This component is typically used in conjunction with the Scaffold component to maintain consistent layout and behavior across different pages in the application.

Import

import top.yukonga.miuix.kmp.basic.TopAppBar
import top.yukonga.miuix.kmp.basic.SmallTopAppBar
import top.yukonga.miuix.kmp.basic.MiuixScrollBehavior
import top.yukonga.miuix.kmp.basic.rememberTopAppBarState

Basic Usage

Small TopAppBar

Scaffold(
    topBar = {
        SmallTopAppBar(
            title = "Title",
            navigationIcon = {
                IconButton(onClick = { /* Handle click event */ }) {
                    Icon(MiuixIcons.Back, contentDescription = "Back")
                }
            },
            actions = {
                IconButton(onClick = { /* Handle click event */ }) {
                    Icon(MiuixIcons.More, contentDescription = "More")
                }
            }
        )
    }
)

Large TopAppBar

Scaffold(
    topBar = {
        TopAppBar(
            title = "Title",
            largeTitle = "Large Title", // If not specified, title value will be used
            navigationIcon = {
                IconButton(onClick = { /* Handle click event */ }) {
                    Icon(MiuixIcons.Back, contentDescription = "Back")
                }
            },
            actions = {
                IconButton(onClick = { /* Handle click event */ }) {
                    Icon(MiuixIcons.More, contentDescription = "More")
                }
            }
        )
    }
)

Large TopAppBar Scroll Behavior (Using Scaffold)

TopAppBar supports changing its display state when content scrolls:

val scrollBehavior = MiuixScrollBehavior()

Scaffold(
    topBar = {
        TopAppBar(
            title = "Title",
            largeTitle = "Large Title", // If not specified, title value will be used
            scrollBehavior = scrollBehavior
        )
    }
) { paddingValues ->
    // Content area needs to consider padding
    LazyColumn(
        modifier = Modifier
            .fillMaxSize()
            // If you want to add the overscroll effect, please add it before the scroll behavior
            .overScrollVertical()
            // Bind TopAppBar scroll behavior
            .nestedScroll(scrollBehavior.nestedScrollConnection),
        contentPadding = PaddingValues(top = paddingValues.calculateTopPadding())
    ) {
        // List content
    }
}

Custom Styles

Custom Colors

TopAppBar(
    title = "Title",
    color = MiuixTheme.colorScheme.primary,
    titleColor = MiuixTheme.colorScheme.onPrimary,
    largeTitleColor = MiuixTheme.colorScheme.onPrimary
)

Custom Content Padding

TopAppBar(
    title = "Title",
    titlePadding = 32.dp
)

Custom Icon Padding

TopAppBar(
    title = "Title",
    navigationIconPadding = 12.dp,
    actionIconPadding = 12.dp
)

Properties

TopAppBar Properties

Property Name	Type	Description	Default Value	Required
title	String	Top bar title	-	Yes
modifier	Modifier	Modifier applied to the top bar	Modifier	No
color	Color	Top bar background color	MiuixTheme.colorScheme.surface	No
titleColor	Color	Color of the collapsed small title text	MiuixTheme.colorScheme.onSurface	No
largeTitle	String	Large title text	title	No
largeTitleColor	Color	Color of the expanded large title text	MiuixTheme.colorScheme.onSurface	No
subtitle	String	Subtitle text displayed below the title bar	""	No
subtitleColor	Color	Color of the subtitle text	MiuixTheme.colorScheme.onSurfaceVariantSummary	No
navigationIcon	@Composable () -> Unit	Composable function for navigation icon area	{}	No
actions	@Composable RowScope.() -> Unit	Composable function for action buttons area	{}	No
scrollBehavior	ScrollBehavior?	Controls top bar scroll behavior	null	No
defaultWindowInsetsPadding	Boolean	Whether to apply default window insets padding	true	No
titlePadding	Dp	Horizontal content padding	TopAppBarDefaults.TitlePadding	No
navigationIconPadding	Dp	Start padding of the navigation icon	TopAppBarDefaults.NavigationIconPadding	No
actionIconPadding	Dp	End padding of the action icons	TopAppBarDefaults.ActionIconPadding	No
bottomContent	@Composable () -> Unit	Composable content displayed below the title bar area	{}	No

SmallTopAppBar Properties

Property Name	Type	Description	Default Value	Required
title	String	Top bar title	-	Yes
modifier	Modifier	Modifier applied to the top bar	Modifier	No
color	Color	Top bar background color	MiuixTheme.colorScheme.surface	No
titleColor	Color	Color of the title text	MiuixTheme.colorScheme.onSurface	No
subtitle	String	Subtitle text displayed below the title bar	""	No
subtitleColor	Color	Color of the subtitle text	MiuixTheme.colorScheme.onSurfaceVariantSummary	No
navigationIcon	@Composable () -> Unit	Composable function for navigation icon area	{}	No
actions	@Composable RowScope.() -> Unit	Composable function for action buttons area	{}	No
scrollBehavior	ScrollBehavior?	Controls top bar scroll behavior	null	No
defaultWindowInsetsPadding	Boolean	Whether to apply default window insets padding	true	No
titlePadding	Dp	Horizontal content padding	TopAppBarDefaults.TitlePadding	No
navigationIconPadding	Dp	Start padding of the navigation icon	TopAppBarDefaults.NavigationIconPadding	No
actionIconPadding	Dp	End padding of the action icons	TopAppBarDefaults.ActionIconPadding	No
bottomContent	@Composable () -> Unit	Composable content displayed below the title bar area	{}	No

TopAppBarDefaults Object

The TopAppBarDefaults object provides default values for TopAppBar and SmallTopAppBar components.

Constants

Constant Name	Type	Description	Default Value
TitlePadding	Dp	Horizontal padding of the title and large title	26.dp
NavigationIconPadding	Dp	Start padding of the navigation icon	16.dp
ActionIconPadding	Dp	End padding of the action icons	16.dp
CollapsedHeight	Dp	Collapsed height of the TopAppBar	52.dp
SmallTopAppBarCenterHeight	Dp	Vertical center height for SmallTopAppBar layout	50.dp
LargeTitleBottomPadding	Dp	Bottom padding below the large title when no subtitle is present	4.dp
SubtitleBottomPadding	Dp	Bottom padding below the subtitle (both large and small)	8.dp

ScrollBehavior

MiuixScrollBehavior is a configuration object used to control the scroll behavior of the top bar.

rememberTopAppBarState

Used to create and remember TopAppBarState:

val scrollBehavior = MiuixScrollBehavior(
    state = rememberTopAppBarState(),
    snapAnimationSpec = spring(stiffness = 2500f),
    canScroll = { true }
)

Parameter Name	Type	Default Value	Description
state	TopAppBarState	rememberTopAppBarState()	State object controlling scroll state
canScroll	() -> Boolean		Callback to control whether scrolling is allowed
snapAnimationSpec	AnimationSpec<Float>?	spring(stiffness = 2500f)	Defines snap animation after scrolling
flingAnimationSpec	DecayAnimationSpec<Float>?	rememberSplineBasedDecay()	Defines decay animation for fling

Advanced Usage

Handling Window Insets

TopAppBar(
    title = "Title",
    largeTitle = "Large Title",
    defaultWindowInsetsPadding = false // Handle window insets manually
)

Custom Scroll Behavior Animation

var isScrollingEnabled by remember { mutableStateOf(true) }
val scrollBehavior = MiuixScrollBehavior(
    snapAnimationSpec = tween(durationMillis = 100),
    flingAnimationSpec = rememberSplineBasedDecay(),
    canScroll = { isScrollingEnabled } // Can dynamically control whether scrolling is allowed
)

TopAppBar(
    title = "Title",
    largeTitle = "Large Title",
    scrollBehavior = scrollBehavior
)

Combining Large and Small Titles

var useSmallTopBar by remember { mutableStateOf(false) }

Box(modifier = Modifier.fillMaxSize()) {
    if (useSmallTopBar) {
        SmallTopAppBar(
            title = "Compact Mode",
            navigationIcon = {
                IconButton(onClick = { useSmallTopBar = false }) {
                    Icon(
                        imageVector = MiuixIcons.Back,
                        contentDescription = "Switch to Large Title",
                        tint = MiuixTheme.colorScheme.onBackground
                    )
                }
            }
        )
    } else {
        TopAppBar(
            title = "Title",
            largeTitle = "Expanded Mode",
            navigationIcon = {
                IconButton(onClick = { useSmallTopBar = true }) {
                    Icon(
                        imageVector = MiuixIcons.Back,
                        contentDescription = "Switch to Small Title",
                        tint = MiuixTheme.colorScheme.onBackground
                    )
                }
            }
        )
    }
}

Changelog

Last edited 5 months ago

View full history

0b7ec07-library: refactor: unify dropdown and spinner components (#315)

a109f90-library: refactor TopAppBar layout (#286)

27fe381-library!: add built-in icon padding to TopAppBar and rename parameters

ad58a82-docs: add icon padding tip for TopAppBar

752a76c-library: enhance animations and add color customization to TopAppBar

80e2357-library: refactor component defaults into dedicated Defaults objects

03b9323-refactor: Migrate all Modifier.composed to Modifier.Node

1769fbb-refactor: Move extended icon to a separate library

4007f40-docs: fix errors

752f3df-docs: Preview for components in documentation website (#80)

4c5a39d-library: feat: Add FloatingToolbar and FloatingNavigationBar component(#69)

f28cdf4-library: Remove LazyColumn Component

6b3526e-docs: Fix document page hyperlink issue

7b99e64-docs: Add English version through AI translation

ab6bb69-chore: Add documents (#63)