Reusable UI Components
Relevant source files
The following files were used as context for generating this wiki page:
- app/src/main/java/com/vocabri/ui/components/Buttons.kt
- app/src/main/java/com/vocabri/ui/components/Cards.kt
- app/src/main/java/com/vocabri/ui/components/ShimmerEffect.kt
- app/src/main/java/com/vocabri/ui/components/modifier/DashedBorderModifier.kt
- app/src/main/java/com/vocabri/ui/components/ChipsFlowRow.kt
- app/src/main/java/com/vocabri/ui/screens/dictionary/DictionaryScreen.kt
- app/src/main/java/com/vocabri/ui/screens/addword/components/NounFields.kt
The Vocabri application leverages a set of reusable Jetpack Compose UI components to ensure a consistent user interface, promote code reuse, and accelerate development. These components are located in the com.vocabri.ui.components package and provide standardized implementations for common UI elements like buttons, cards, and dynamic layouts.
This document outlines the key reusable components, their functionalities, and how they are used throughout the application. The components are designed to be flexible and customizable, adhering to the Material 3 design principles established in the project's theme.
Core Components
Buttons
The Buttons.kt file defines a Buttons object containing several standardized button composables used across the app. These provide a consistent look and feel for user actions.
Buttons.Filled: A standard filled button with text and an optional leading icon.Buttons.Outlined: An outlined button with text and an optional leading icon.Buttons.Text: A text-only button.
The following table summarizes the common parameters for these button composables.
| Parameter | Type | Description |
|---|---|---|
modifier | Modifier | The modifier to be applied to the button. |
text | String | The text to display on the button. |
icon | ImageVector? | An optional icon to display before the text. |
contentDescriptionResId | @StringRes Int? | Optional string resource ID for the icon's content description. |
onClick | () -> Unit | The callback to be invoked when the button is clicked. |
Sources: app/src/main/java/com/vocabri/ui/components/Buttons.kt:29-81
Cards
The Cards.kt file provides an object for creating card-based UI elements with built-in styling for shadows and interactions. It offers two main types of cards: Solid and Gradient. A key feature is the conditional application of a shadow modifier, which is only applied in light theme mode to maintain visual design integrity.
Sources: app/src/main/java/com/vocabri/ui/components/Cards.kt:40-48, app/src/main/java/com/vocabri/ui/components/Cards.kt:85-93
This diagram shows the structure of the Cards object and its composable functions.
Cards.Solid
This composable creates a card with a solid background color. It uses MaterialTheme.colorScheme.primaryContainer as the default color.
Sources: app/src/main/java/com/vocabri/ui/components/Cards.kt:32-52
Cards.Gradient
This composable creates a card with a horizontal gradient background. It accepts a list of colors to create the Brush.
Sources: app/src/main/java/com/vocabri/ui/components/Cards.kt:76-100
ChipsFlowRow
ChipsFlowRow is a generic composable that arranges a list of items in a FlowRow, making it ideal for displaying tags or selectable options that wrap to the next line. It is highly reusable due to its generic type parameter <T : Any>.
Key features include:
- Displaying a list of any type (
items: List<T>). - A lambda to define how to display each item (
itemPrintableName: @Composable (T) -> String). - Handling selection state (
isSelected: (T) -> Boolean). - Supporting item removal with a clear icon (
removable: Boolean).
Sources: app/src/main/java/com/vocabri/ui/components/ChipsFlowRow.kt
The following diagram illustrates the logic for rendering each chip within the ChipsFlowRow.
This component is used in the "Add Word" screen to display gender options for nouns.
Sources: app/src/main/java/com/vocabri/ui/screens/addword/components/NounFields.kt:41-47
Visual Effects and Modifiers
ShimmerEffect
The ShimmerEffect composable provides a skeleton loading animation. It draws a box with a shimmering gradient that animates across its surface. This is used to indicate that content is loading, such as on the DictionaryScreen.
The shimmer is created using a Brush.linearGradient with an animated translateAnimation value, which shifts the gradient's position over time.
Sources: app/src/main/java/com/vocabri/ui/components/ShimmerEffect.kt:31-55, app/src/main/java/com/vocabri/ui/screens/dictionary/DictionaryScreen.kt:140-166
DashedBorderModifier
The dashedBorder is a custom Modifier extension function that draws a dashed border around a composable. It is implemented using drawWithContent and drawPath.
The appearance of the dash can be configured with the following parameters:
| Parameter | Type | Description | Default Value |
|---|---|---|---|
strokeWidth | Dp | The width of the border stroke. | 1.dp |
color | Color | The color of the border. | Color.Gray |
onPhase | Dp | The length of the painted segment. | 10.dp |
offPhase | Dp | The length of the unpainted segment. | 10.dp |
shape | Shape | The shape of the border. | Rectangle |
Sources: app/src/main/java/com/vocabri/ui/components/modifier/DashedBorderModifier.kt:29-54
Component Usage Example
The reusable components are composed together to build complex screens. The DictionaryScreen provides a clear example of this, using ShimmerEffect for its loading state and Buttons for user actions in its empty state.
The diagram below shows how DictionaryScreen is composed of smaller, reusable parts depending on its state.
Conclusion
The reusable UI components in the Vocabri project form a robust and flexible library for building the application's user interface. By encapsulating common UI patterns into composables like Buttons, Cards, and ChipsFlowRow, the codebase remains clean, consistent, and easy to maintain. Custom modifiers and effects like dashedBorder and ShimmerEffect further enhance the UI's visual appeal and user experience. This component-based architecture is fundamental to the app's scalability and development efficiency.