Skip to main content

Material design for django forms and admin

Project description

Material design for Django Forms and Admin. Template driven. Join the chat at


  • Forms - New way to render django forms

    • Strong python/html code separation

    • Easy redefinition of particular fields rendering

    • Complex form layout support

  • Frontend - Quick starter template for modular applications development

  • Admin - Material-designed django admin




django-material tested with Python 2.7/3.4/3.5, django 1.8, django 1.9:

pip install django-material


Add material into INSTALLED_APPS settings


Include material javascript and styles along with jQuery into your base template.

{% include 'material/includes/material_css.html' %}
<script src="{% static 'material/js/jquery-2.2.0.js' %}"></script>
{% include 'material/includes/material_js.html' %}

Load the material_form template tag library

{% load material_form %}

And render your form with {% form %} template tag

<form method="POST">
    {% csrf_token %}
    {% form form=form %}{% endform %}
    <button type="submit" name="_submit" class="btn">Submit</button>

Template tags

django-material forms processing is built around simple concept called part. part is like django template block, it has a default value and could be overriden. But parts are created dynamically for each form field, which allows you to redefine specific form field html render output.

Here is the example of rendering form with but prefix email field with email icon.

<form method="POST">
    {% csrf_token %}
    {% form %}
        {% part prefix %}<div class="input-group-addon">@</div>{% endpart %}
    {% endform %}
    <button type="submit" name="_submit" class="btn">Submit</button>

You can append value to of some tags attribute or completly override the attribute content.

{% form %}
    {% attr 'group' class append %}yellow{% endattr %}
    {% attr 'label' class append %}big{% endattr %}
    {% attr 'widget' data-validate %}email{% endattr %} <!-- by default value would be overriden -->
    {% attr 'widget' placeholder override %}{% endattr %}
{% endform %}

There is a lot of other parts and attribute groups declared in default templates. See template code for details. If your widget is so special, you can completly override its rendering

{% part form.my_field %}any html code here{% endpart %}


Layout object is the way to specify relative fields placements and sizes.

from material import *

layout = Layout(
    Row('shipment_no', 'description')
    Fieldset("Add to inventory",
             Row(Span3('product_name'), 'tags'),
             Row('vendor', 'product_type'),
                 'gender', 'desired_gender'),
             Row('cost_price', Span2('wholesale_price'), 'retail_price')))

SpanXX elements are not to material grid classes, but used to determine relative fields width. Each row occupies 12 grid columns. Elements in Row(‘elem1’, ‘elem2’) would be rendered in 6 grid coulmns each, and in Row(Span2(‘elem1’), ‘elem2’) elem1 would be rendered in 8 grid columns, and elem2 in 4 grid columns.

Layouts rendering itself is specified in template.

ModelForm Views

Material forms library provides LayoutMixin for model form views, populates form fields list directly from layout object

from django import generic
from viewform import LayoutMixin

class SampleView(LayoutMixin, generic.ModelFormView):
    layout = Layout(...)


Frontend template assumes that your application contains a set of top level modules each one could restrict user access level and have own submenu.

To quick start add material.frontend into INSTALLED_APPS settings


Add frontend urls into global urlconf module at

from material.frontend import urls as frontend_urls

urlpatterns = [
    url(r'', include(frontend_urls)),

The fronend module perform all required settings modification (add middleware, context_processors and template tags), automagically till MATERIAL_FRONTEND_AUTOREGISTER settings set to False.

To create a new module add ModuleMixin to your AppConfig definision in

from material.frontend.apps import ModuleMixin

class Sales(ModuleMixin, AppConfig):
    name = 'sales'
    icon = '<i class="mdi-communication-quick-contacts-dialer"></i>'

The application have to have <app_module>/ file, with a single no-parametrized url with name=’index’, ex

urlpatterns = [
        url('^$', generic.TemplateView.as_view(template_name="sales/index.html"), name="index"),

All AppConfigs urls will be included into material.frontend.urls automatically under /<app_label>/ prefix The AppConfig.label, used for the urls namespace.

The menu.html sample

    <li><a href="{% url 'sales:index' %}">Dashboard</a></li>
    <li><a href="{% url 'sales:customers' %}">Customers</a></li>
    {% if perms.sales.can_add_lead %}<li><a href="{% url 'sales:leads' %}">Leads</a></li>{% endif %}

After you create a new module, you need to run ./ migrate.

You can manage module installed state on the django admin page - /admin/frontend/module/


Add material.admin into INSTALLED_APPS settings


NOTE: ‘material.admin’ must be added before ‘django.contrib.admin’

Ensure that django.template.context_processors.request in your template context processor settings list

        'OPTIONS': {
            'context_processors': [

You can provide a custom admin site module in the MATERIAL_ADMIN_SITE setting

MATERIAL_ADMIN_SITE = 'mymodule.admin.admin_site'

Admin support development is on initial stage. Only basic admin features are available.


0.8.0 2016-06-14 - Beta

First beta release.

  • Forms - Fix 0 as initial value for number input

  • Forms - Remove Roboto font fix hack on windows

  • Frontend - module heareds fixed

  • Admin - list sorting support

  • Admin - fixedHeader fixed

  • Admin - fix pagination display bug under dj19

  • Admin - lost actions support

  • Admin - added datetime today shortcut links

  • Admin - added filter for select multiple field

  • Admin - readonly fields support for inlines

  • Admin - mansory layout for index page

  • Admin - added app and model icons support

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-material-0.8.0.tar.gz (1.6 MB view hashes)

Uploaded Source

Built Distribution

django_material-0.8.0-py2.py3-none-any.whl (1.7 MB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page