An Android TextView that always displays an auto refreshing relative time span with respect to a reference time

Min SDK   8
Latest Commit   2017-08-09 06:39:40
License   unknown







Android developer


android-circlebutton Circle button widget for Android
Android-RobotoTextView Implementation of a TextView and all its direct/indirect subclasses with native support for the Roboto fonts, includes the brand new Roboto Slab fonts.
BubbleTextView Android Bubble View


This library provides RelativeTimeTextView, a custom TextView that takes a reference time and always displays the relative time with respect to the reference point, automatically refreshing the display text as needed. This is a common pattern seen in several apps like chat apps, social networking, email etc.

Here is a screenshot from the sample app

This library can be seen as a wrapper on top of the excellent android.text.format.DateUtils class. Note that the library does not expose all the options provided by the DateUtils class. I have left out many features because I couldn't decide what would be the best way to achieve the flexibility - dozens of XML attributes? Contributions in this regard are welcome.



Add the following to your build.gradle

dependencies {
    compile ''

Important: v1.3.4 Fixed a major bug (#47). If you are using an older version, please update to 1.3.4 now.


  1. Clone the repo
  2. In Eclipse, go to File -> New -> Other. Expand Android and select Android Project from Existing Code
  3. Browse to the android-ago sub-folder of the cloned repo and hit Finish


  • Include RelativeTimeTextView in your layouts.
  • Set the reference time either using setReferenceTime method or using the XML attribute reference_time.
  • Optionally, you can set a prefix using relative_time_prefix through XML or setPrefix from Java code.
  • Similarly, you can set a suffix using relative_time_suffix through XML or setSuffix from Java code.

In your layout:

    app:relative_time_prefix="Completed "
    android:layout_marginTop="@dimen/margin_primary" />

In your Java code:

RelativeTimeTextView v = (RelativeTimeTextView)findViewById(; //Or just use Butterknife!
v.setReferenceTime(new Date().getTime());

See the sample project for a concrete example.

Why is this library even needed?

One might ask, why not just use DateUtils directly? Well, the answer is that the custom TextView provided by this library is responsible for keeping track of its own reference time and of updating the display text over regular periodic intervals. It is also responsible for scheduling (or cancelling a scheduled) update of the display text. All you have to do is set the reference time once.

Who's Using this Library?

See here. If you would like to add your app to this list, please edit the wiki.

Android version support statement

The library has been tested on API 11 and above. However, theoretically, it works on API 3 and above since all it uses is [DateUtils#getRelativeTimeSpanString](, long, long, int)).

The minSdkVersion has been set to 8, however do not expect support from me for API version < 11.

Usage with Data Binding

See android-ago-sample-databinding for an example of how to use this library with the Android data binding library. Thanks to @Dev-IL for providing this sample.


Copyright 2017 Kiran Rao

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

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.