This extension enhances Jinja2 templates with formatting of dates and times using day.js. It is a fork of Flask-Moment that replaces moment.js with day.js, the modern, actively maintained successor.
moment.js is officially in maintenance mode — no longer developed, only patched — and its own maintainers recommend day.js as a drop-in alternative. day.js is API-compatible with moment.js for the common cases, immutable, and much smaller:
| Library | Default page payload* |
|---|---|
| Flask-Moment with all locales | ~73 KB gz |
| Flask-Moment core only (English) | ~19 KB gz |
| Flask-Dayjs (day.js core + 5 plugins) | ~6 KB gz |
| Flask-Dayjs core only (English) | ~3 KB gz |
*Measured at dayjs 1.11.19 vs. moment 2.29.4.
Flask-Moment bundled every locale into a single script, which is what made it so heavy. day.js ships only a tiny core, and Flask-Dayjs loads individual locales from the CDN only when you ask for them. Even against moment's English-only core build, day.js is about three times smaller.
Install the extension with pip:
pip install flask-dayjsor with uv:
uv add flask-dayjsOnce the extension is installed, create an instance and initialize it with the Flask application:
from flask_dayjs import Dayjs
dayjs = Dayjs(app)If the application uses the application factory pattern, the two-step initialization method can be used instead:
dayjs = Dayjs()
def create_app():
app = Flask(__name__)
dayjs.init_app(app)
return appTo complete the initialization, add the following line inside the <head>
section of the template(s) that will use the extension. If you use template
inheritance, the best place to add this line is in your base template:
{{ dayjs.include_dayjs() }}The include_dayjs() function accepts a few arguments that control settings
such as the version of day.js to use, or whether the library should be
imported from a CDN. See the
API reference below.
Note that older versions of Flask-Moment required jQuery; this is not the case anymore.
To render a date with Flask-Dayjs, use the dayjs() function with one of
the available formatting options. The following example uses a custom format
string to render the current time:
<p>Current date and time: {{ dayjs().format('MMMM D YYYY, h:mm:ss a') }}.</p>To render a timestamp other than the current time, pass a datetime object
as an argument to the dayjs() function:
<p>Date: {{ dayjs(date).format('LL') }}</p>Some of the rendering functions render the elapsed time between a datetime object and current time. The following example renders a timestamp in a "time ago" style:
<p>{{ author }} said {{ dayjs(comment_datetime).fromNow() }}</p>All the display functions take an optional refresh argument that when set
to True will re-render timestamps every minute. If a different time
interval is desired, pass the interval in minutes as the value of the
refresh argument.
This option is useful for relative time formats such as the one returned by
the fromNow() or fromTime() functions. For example, the date of a
comment would appear as "a few seconds ago" when the comment was just entered,
but a minute later it would automatically refresh to "a minute ago" without
the need to refresh the page.
By default automatic refreshing is disabled.
The format() function can be invoked without arguments, in which case a
default format of ISO8601 defined by the day.js library is used. If you want
to set a different default, you can set the DAYJS_DEFAULT_FORMAT variable
in the Flask configuration. Consult the
day.js format documentation for
a list of accepted tokens.
By default dates and times are rendered in English. To change to a different
language add the following line in the <head> section of your template(s),
after the include_dayjs() line:
{{ dayjs.locale("es") }}The above example sets the language to Spanish. Each dayjs.locale() call
both loads the requested locale's data from the CDN and activates it. Unlike
Flask-Moment, which bundled every locale into a single script, Flask-Dayjs
only downloads the locales you actually use (the browser caches them, so
calling dayjs.locale("es") on multiple pages costs nothing after the
first load). Day.js supports a large number of languages. Consult the
documentation for the list of languages and their corresponding codes.
This extension also supports auto-detection of the client's browser language:
{{ dayjs.locale(auto_detect=True) }}With auto-detection enabled, the locale matching the browser's language is
loaded automatically from the CDN, so no manual dayjs.locale() call is
needed. If your application supports a known set of languages, you can still
pre-load them eagerly to avoid a brief flash of English:
{{ dayjs.locale("es") }}
{{ dayjs.locale("fr") }}
{{ dayjs.locale(auto_detect=True) }}Custom locale data can be passed as a dictionary:
{{ dayjs.locale("es", customization={"months": ["enero", ...]}) }}It is also possible to create Flask-Dayjs timestamps in Python code that is invoked from the client page through Ajax, without the use of Jinja templates:
timestamp = dayjs.create(datetime.now(timezone.utc)).calendar()The dayjs variable is the Dayjs instance that was created at
initialization time.
A timestamp created in this way is an HTML string that can be returned as part of a response. For example, here is how a timestamp can be returned in a JSON object:
return {'timestamp': dayjs.create(datetime.now(timezone.utc)).format('L')}The Ajax callback in the browser needs to call flask_dayjs_render_all()
each time an element containing a timestamp is added to the DOM. The example
application in the Flask-Dayjs GitHub repository demonstrates how this is
done.
SRI is a security feature that enables browsers to verify that resources they fetch are not maliciously manipulated. To do so a cryptographic hash is provided that proves integrity.
SRI for the day.js library is enabled by default. If you wish to use a version different than the one bundled with this extension, or want to host your own JavaScript, a separate hash can be provided.
Just add sri=<YOUR-HASH> when calling dayjs.include_dayjs(). If no SRI
hash is provided when a custom day.js version is used, then SRI verification
is not used.
To disable SRI, pass sri=False in the include_dayjs() call.
Flask-Dayjs is a drop-in replacement for Flask-Moment with the syntax renamed
from moment to dayjs:
| Flask-Moment | Flask-Dayjs |
|---|---|
from flask_moment import Moment |
from flask_dayjs import Dayjs |
moment = Moment(app) |
dayjs = Dayjs(app) |
{{ moment.include_moment() }} |
{{ dayjs.include_dayjs() }} |
{{ moment().format('LL') }} |
{{ dayjs().format('LL') }} |
moment.locale("es") |
dayjs.locale("es") |
MOMENT_DEFAULT_FORMAT config |
DAYJS_DEFAULT_FORMAT config |
The rendering methods (format, fromNow, fromTime, toNow,
toTime, calendar, valueOf, unix, diff), the create()
and lang() helpers, and the local and refresh arguments behave
identically.
Note that day.js and moment.js are different libraries, so a few formatting tokens may render differently, and day.js parses ISO 8601 strings more strictly than moment.js.
The complete API is documented in the docstrings of the source module. In short:
dayjs.include_dayjs(version, local_js, no_js, sri, plugins)— include day.js and the supporting JavaScript in the<head>section.dayjs.locale(language, auto_detect, customization)anddayjs.lang(language)— configure the locale.dayjs.flask_day_js()— the raw supporting JavaScript, for custom setups.dayjs(timestamp=None, local=False)— create a dayjs object in a template, with the rendering methods listed above.Dayjs(app)/Dayjs().init_app(app)— initialize the extension.Dayjs.create(timestamp)— create a rendered timestamp outside of templates (e.g. for Ajax responses).