Awesome
Seeker
Seeker is a highly customizable seekbar/slider for Android with support for readahead indicator and segments. Made with Jetpack Compose ❤.
<a href="https://jetc.dev/issues/154.html"><img src="https://img.shields.io/badge/As_Seen_In-jetc.dev_Newsletter_Issue_%23154-blue?logo=Jetpack+Compose&logoColor=white" alt="Featured In - jetc.dev Newsletter Issue #154"></a>
Including in your project
Gradle
Add the dependency below to your module's build.gradle
file:
dependencies {
implementation 'io.github.2307vivek:seeker:1.2.2'
}
How to use
You can create a Seeker with the Seeker
composable.
@Composable
fun Seeker(
modifier: Modifier = Modifier,
state: SeekerState = rememberSeekerState(),
value: Float,
range: ClosedFloatingPointRange<Float> = 0f..1f,
readAheadValue: Float = range.start,
onValueChange: (Float) -> Unit,
onValueChangeFinished: (() -> Unit)? = null,
segments: List<Segment> = emptyList(),
enabled: Boolean = true,
colors: SeekerColors = SeekerDefaults.seekerColors(),
dimensions: SeekerDimensions = SeekerDefaults.seekerDimensions(),
interactionSource: MutableInteractionSource = remember { MutableInteractionSource() },
)
In its simplest form seeker can be used as a regular slider for selecting values from a range or showing progress in a range.
var value by remember { mutableStateOf(0f) }
Seeker(
value = value,
range = 1f..100f,
onValueChange = { value = it }
)
Read Ahead indicator
A read-ahead indicator shows the amount of content that is already ready to use. It is particularly useful in media streaming apps where some media is downloaded ahead of time to avoid buffering. The readAheadValue
property of the Seeker composable can be used to display the read ahead indicator.
var value by remember { mutableStateOf(0f) }
var readAheadValue by remember { mutableStateOf(0f) }
Seeker(
value = value,
readAheadValue = readAheadValue,
range = 1f..100f,
onValueChange = { value = it }
)
Creating Segments
Seeker can break the track into different sections, which can be used to display different parts in the range. To create segments, a list of Segment
needs to be passed in the Seeker
composable.
val segments = listOf(
Segment(name = "Intro", start = 1f),
Segment(name = "Part 1", start = 40f),
Segment(name = "Part 2", start = 88f),
)
Seeker(
value = value,
readAheadValue = readAheadValue,
range = 1f..100f,
segments = segments,
onValueChange = { value = it }
)
The Segment
takes the name
and the start
value form which the segments shlould start. You can also pass an optional color parameter to each segment.
The first segment in the list must start from the start point of the range, and all the segments must lie in the range of the seeker, otherwise an IllegalArgumentException
will be thrown to avoid unexpected behavior.
Segments are by default separated by a gap in the track, which can be customized by passing a dimensions
parameter in the composable.
Seeker(
value = value,
readAheadValue = readAheadValue,
range = 1f..100f,
segments = segments,
dimensions = SeekerDefaults.seekerDimensions(gap = 4.dp),
onValueChange = { value = it }
)
Observing current segment
The current segment corresponding to the current seeker value can be observed by using the currentSegment
property of the SeekerState
which can be created by using rememberSeekerState()
.
val segments = listOf(
Segment(name = "Intro", start = 1f),
Segment(name = "Part 1", start = 40f),
Segment(name = "Part 2", start = 88f),
)
val state = rememberSeekerState()
Seeker(
state = state,
value = value,
readAheadValue = readAheadValue,
range = 1f..100f,
segments = segments,
onValueChange = { value = it }
)
//Observing the current segment
Text(state.currentSegment.name)
Customizing Seeker
Seeker is highly customizable in terms of its dimensions and colors. The seekerColors()
and seekerDimensions()
functions can be used to customise the colors and dimensions of the different parts of seeker.
The seekerColors()
and seekerDimensions()
functions are as follows:
@Composable
fun seekerColors(
progressColor: Color = MaterialTheme.colors.primary,
trackColor: Color = TrackColor,
disabledProgressColor: Color = MaterialTheme.colors.onSurface.copy(alpha = DisabledProgressAlpha),
disabledTrackColor: Color = disabledProgressColor.copy(alpha = DisabledTrackAlpha).compositeOver(MaterialTheme.colors.onSurface),
thumbColor: Color = MaterialTheme.colors.primary,
disabledThumbColor: Color = MaterialTheme.colors.onSurface.copy(alpha = ContentAlpha.disabled).compositeOver(MaterialTheme.colors.surface),
readAheadColor: Color = ReadAheadColor
): SeekerColors
@Composable
fun seekerDimensions(
trackHeight: Dp = TrackHeight,
progressHeight: Dp = trackHeight,
thumbRadius: Dp = ThumbRadius,
gap: Dp = Gap
): SeekerDimensions
The seeker composable has parameters colors
and dimensions
which can be used to customize the colors and dimensions of the seeker respectively.
Seeker(
value = value,
readAheadValue = readAheadValue,
range = 1f..100f,
segments = segments,
colors = SeekerDefaults.colors(trackColor = customColor, thumbColor = customThumbColor, ...)
dimensions = SeekerDefaults.seekerDimensions(gap = 4.dp, thumbRadius = 12.dp, ...),
onValueChange = { value = it }
)
Note: As of the current version, unexpected behaviors are noted when colors with an alpha value less than 1f are used in the seeker. You shluld avoid using transparent colors in seeker. See issue #12.
The above functions are @Composables
which means it will be recomposed when the parameters change. It can be used to animate the colors and dimensions of seeker.
val interactionSource = remember { MutableInteractionSource() }
val isDragging by interactionSource.collectIsDraggedAsState()
val gap by animateDpAsState(if (isDragging) 2.dp else 0.dp)
val thumbRadius by animateDpAsState(if (isDragging) 10.dp else 0.dp)
Seeker(
value = value,
readAheadValue = readAheadValue,
range = 1f..100f,
segments = segments,
interactionSource = interactionSource,
colors = SeekerDefaults.colors(trackColor = customColor, thumbColor = customThumbColor)
dimensions = SeekerDefaults.seekerDimensions(gap = gap, thumbRadius = thumbRadius),
onValueChange = { value = it }
)
Using different value for thumb
Seeker has the ability to provide a separate value for the thumb, which makes it possible to move the thumb independently of the progress.
var value by remember{ mutableStateOf(0f) }
var thumbPosition by remember{ mutableStateOf(0f) }
val isDragging by interactionSource.collectIsDraggedAsState()
Seeker(
value = value,
thumbValue = if (isDragging) thumbPosition else value,
onValueChange = { thumbPosition = it },
onValueChangeFinished = { value = thumbPosition },
readAheadValue = readAheadValue,
interactionSource = interactionSource,
range = 1f..100f,
...
)
Making two-way Seeker
You can also make a two-way slider by providing the start position as a fraction of the track width using the progressStartPosition
parameter.
var value by remember { mutableStateOf(0f) }
Seeker(
value = value,
progressStartPosition = 0.3f,
range = 1f..100f,
onValueChange = { value = it }
)
Find this library useful? :heart:
Support it by joining stargazers for this repository. :star: <br> Also, follow me on github and twitter to stay updated with my creations! 🤩
License
Copyright 2023 Vivek Singh
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.