Django Vibe Components

material/base.html

The foundational template that sets up the HTML document structure, includes required CSS and JavaScript, and defines the basic layout.

{% extends 'material/base.html' %}

{% block title %}My Custom Title{% endblock %}

{% block body %}
  
{% endblock %}

Block Name	Default Content	Description
`favicon`	Link to default favicon	Customize the favicon for your application
`title`	`Django Vibe Components`	Set the page title
`css`	Core stylesheets	Include additional or override default stylesheets
`layout_css`	Layout stylesheet	Override the layout stylesheet
`js`	Core JavaScript files	Include additional or override default JavaScript
`extrahead`	Empty	Add additional content to the head section
`body`	Empty	The main content area of the page

material/base_page.html

Extends base.html and provides a standard page layout with navigation, main content area, and footer. This is the recommended template to extend for most pages.

{% extends 'material/base_page.html' %}

{% block nav_header %}
  
{% endblock %}

{% block nav_items %}
  
  <c-nav.item icon="home" href="/">Home</c-nav.item>
{% endblock %}

{% block nav_footer %}
  
{% endblock %}

{% block nav %}
  
  
{% endblock %}

{% block content %}
  
{% endblock %}

{% block footer %}
  
{% endblock %}

Block Name	Default Content	Description
`nav`	Navigation container with slots	Override the entire navigation component
`nav_header`	Empty	Content for the navigation header
`nav_items`	Empty	Navigation menu items
`nav_footer`	Empty	Content for the navigation footer
`content`	Empty	Main content area of the page
`footer`	Empty	Footer content
`extrabody`	Empty	Additional content at the end of the body

Customization Examples

Customizing the Navigation

{% extends 'material/base_page.html' %}

{% block nav_header %}
  <div class="flex items-center mb-2">
    <span class="material-symbols mr-2">dashboard</span>
    <span class="text-lg font-semibold text-primary">My Application</span>
  </div>
{% endblock %}

{% block nav_items %}
  <c-nav.item icon="home" href="{% url 'home' %}">Home</c-nav.item>
  <c-nav.item icon="person" href="{% url 'profile' %}">Profile</c-nav.item>
  <c-nav.item icon="settings" href="{% url 'settings' %}">Settings</c-nav.item>
{% endblock %}

{% block nav_footer %}
  <div class="flex items-center">
    <span class="material-symbols mr-2">account_circle</span>
    <span>John Doe</span>
  </div>
{% endblock %}

Adding Custom CSS and JavaScript

{% extends 'material/base_page.html' %}

{% block css %}
  {{ block.super }}
  <link rel="stylesheet" href="{% static 'myapp/css/custom.css' %}">
{% endblock %}

{% block js %}
  {{ block.super }}
  <script src="{% static 'myapp/js/custom.js' %}"></script>
{% endblock %}

Customizing the Page Title

{% extends 'material/base_page.html' %}

{% block title %}{{ object.title }} | My Application{% endblock %}

Template Customization

Django Material templates follow Django's template inheritance system, allowing you to override any template in your project. This makes it easy to customize the appearance and functionality of Material components without modifying the core files.

Overriding Templates

To override any Django Material template, you can create a template with the same path in your project's templates directory. First, ensure your templates directory is properly configured in your Django settings:

TEMPLATES = [
{
    'BACKEND': 'django.template.backends.django.DjangoTemplates',
    'DIRS': [
        # ./templates/ subdirectory is located at the same folder as ./manage.py
        os.path.join(BASE_DIR, 'templates')
    ],
    ...
}
]

To override a component template, create a file with the same path in your templates directory. For example, to override material/base.html, create a file at:

templates/material/base.html

Extending and Modifying Templates

The recommended approach is to extend the original template and override only the blocks you want to customize. This ensures your template will continue to work even if the original template is updated.

{% extends 'material/base.html' %}
{% load i18n static %}

{% block title %}{{ site.title|default:"Corp. Ink." }}{% endblock %}

{% block css %}
  {{ block.super }}
  <link rel="stylesheet" href="{% static 'myapp/css/custom.css' %}">
{% endblock %}

This approach works for any template, including component templates in the cotton/ directory. For example, to customize the filled button template:

templates/cotton/button/filled.html

Overriding Cotton Components

Cotton components can be overridden just like any other template. When you override a component template, all instances of that component in your application will use your customized version.

{% extends 'cotton/button/filled.html' %}
{% load i18n static %}

<c-vars
  class="inline-flex items-center justify-center px-6 py-3 
         bg-primary text-on-primary rounded-full shadow-lg {{ class }}" />

<button class="{{ class }}" {{ attrs }}>
  {% if icon %}
  <span class="material-symbols mr-2 leading-tight">{{ icon }}</span>
  {% endif %}
  {{ slot }}
</button>

Base Templates