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

TIP

The navigationIcon and actions slots do not include built-in horizontal padding. You need to manually add padding to the icons (e.g., Modifier.padding(start = 16.dp) for navigation icons and Modifier.padding(end = 16.dp) for action icons) to maintain proper spacing from the edges.

Small TopAppBar

Scaffold(
    topBar = {
        SmallTopAppBar(
            title = "Title",
            navigationIcon = {
                IconButton(
                    onClick = { /* Handle click event */ },
                    modifier = Modifier.padding(start = 16.dp)
                ) {
                    Icon(MiuixIcons.Back, contentDescription = "Back")
                }
            },
            actions = {
                IconButton(
                    onClick = { /* Handle click event */ },
                    modifier = Modifier.padding(end = 16.dp)
                ) {
                    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 */ },
                    modifier = Modifier.padding(start = 16.dp)
                ) {
                    Icon(MiuixIcons.Back, contentDescription = "Back")
                }
            },
            actions = {
                IconButton(
                    onClick = { /* Handle click event */ },
                    modifier = Modifier.padding(end = 16.dp)
                ) {
                    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",
    horizontalPadding = 32.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
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
horizontalPadding	Dp	Horizontal content padding	TopAppBarDefaults.HorizontalPadding	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
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
horizontalPadding	Dp	Horizontal content padding	TopAppBarDefaults.HorizontalPadding	No

TopAppBarDefaults Object

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

Constants

Constant Name	Type	Description	Default Value
HorizontalPadding	Dp	Horizontal padding of the title and large title	26.dp
CollapsedHeight	Dp	Collapsed height of the TopAppBar	56.dp
SmallTopAppBarCenterHeight	Dp	Vertical center height for SmallTopAppBar layout	60.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 },
                    modifier = Modifier.padding(start = 16.dp)
                ) {
                    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 },
                    modifier = Modifier.padding(start = 16.dp)
                ) {
                    Icon(
                        imageVector = MiuixIcons.Back,
                        contentDescription = "Switch to Small Title",
                        tint = MiuixTheme.colorScheme.onBackground
                    )
                }
            }
        )
    }
}

Changelog

Last edited 20 minutes ago

View full history

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)