Skip to main content
The Button component provides a consistent way to create interactive elements with multiple visual variants. It can render as a button, submit input, or link depending on the props provided.

​
Basic Usage

{% load unfold %}

{% component "unfold/components/button.html" %}
  Click Me
{% endcomponent %}

​
Props

​
href
string
URL to navigate to. When provided, renders as an <a> tag instead of <button>.
​
variant
string
default:"primary"
Button style variant. Options:
  • primary - Primary action button (blue)
  • default - Default button (white/transparent)
  • secondary - Secondary button (gray)
  • ghost - Transparent button
  • danger - Destructive action (red)
​
size
string
Button size. Options:
  • Default (not specified)
  • md - Medium size with larger padding
​
submit
boolean
default:"false"
When true, sets type="submit" on button element.
​
form
string
ID of the form this button is associated with (for submit buttons).
​
name
string
Name attribute for the button.
​
value
string
Value attribute for the button.
​
title
string
Tooltip text displayed on hover.
​
class
string
Additional CSS classes to apply to the button.
​
attrs
dict
Dictionary of additional HTML attributes, including disabled.
​
children
string
Button label or content. Passed via the component body.

​
Examples

​
Button Variants

{# Primary button (default) #}
{% component "unfold/components/button.html" %}
  Save
{% endcomponent %}

{# Default variant #}
{% component "unfold/components/button.html" with variant="default" %}
  Cancel
{% endcomponent %}

{# Secondary variant #}
{% component "unfold/components/button.html" with variant="secondary" %}
  Options
{% endcomponent %}

{# Ghost variant #}
{% component "unfold/components/button.html" with variant="ghost" %}
  View More
{% endcomponent %}

{# Danger variant #}
{% component "unfold/components/button.html" with variant="danger" %}
  Delete
{% endcomponent %}

{% component "unfold/components/button.html" with href="/admin/" %}
  Go to Dashboard
{% endcomponent %}

​
Submit Button

{% component "unfold/components/button.html" with submit=1 form="user_form" name="_save" %}
  Save Changes
{% endcomponent %}

​
Button with Icon

{% component "unfold/components/button.html" with variant="default" %}
  <span class="material-symbols-outlined text-base">add</span>
  Add New
{% endcomponent %}

​
Disabled Button

{% component "unfold/components/button.html" with attrs=attrs_disabled %}
  Disabled
{% endcomponent %}

{# In Python/view context #}
context = {
    'attrs_disabled': {'disabled': True}
}

​
Button Sizes

{# Default size #}
{% component "unfold/components/button.html" %}
  Default
{% endcomponent %}

{# Medium size #}
{% component "unfold/components/button.html" with size="md" %}
  Medium Button
{% endcomponent %}

​
Full Width Button

{% component "unfold/components/button.html" with class="w-full" %}
  Full Width Button
{% endcomponent %}

​
Usage in Admin

​
Submit Line Example

From src/unfold/templates/admin/submit_line.html:8-10: 
{% if show_save %}
  {% component "unfold/components/button.html" with submit=1 form=opts.model_name|add:"_form" name="_save" class="w-full lg:w-auto" %}
    {% trans "Save" %}
  {% endcomponent %}
{% endif %}

​
Custom Actions

{% for action in actions_submit_line %}
  {% component "unfold/components/button.html" with submit=1 form=opts.model_name|add:"_form" name=action.action_name variant="default" class="w-full lg:w-auto" %}
    {% if action.icon %}
      <span class="material-symbols-outlined">{{ action.icon }}</span>
    {% endif %}
    {{ action.description }}
  {% endcomponent %}
{% endfor %}

​
Python Integration

​
Layout Component

From src/unfold/layout.py:24-26: 
from crispy_forms.layout import BaseInput
from unfold.widgets import BUTTON_CLASSES

class Button(ButtonClassesMixin, BaseInput):
    input_type = "button"

​
Using in Forms

from unfold.layout import Button, Submit
from crispy_forms.helper import FormHelper
from crispy_forms.layout import Layout

class MyForm(forms.Form):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.helper = FormHelper()
        self.helper.layout = Layout(
            'field_name',
            Submit('submit', 'Save'),
            Button('cancel', 'Cancel')
        )

​
Styling

Button classes from src/unfold/widgets.py:42-54: 
BUTTON_CLASSES = [
    "border",
    "cursor-pointer",
    "font-medium",
    "px-3",
    "py-2",
    "rounded-default",
    "text-center",
    "whitespace-nowrap",
    "bg-primary-600",
    "border-transparent",
    "text-white",
]

​
Accessibility

  • Disabled buttons have opacity-50 and cursor-not-allowed
  • Submit buttons properly set type="submit"
  • Link buttons render as <a> tags for proper keyboard navigation
  • Icon buttons include text labels for screen readers
  • Card - Use buttons in card headers/footers
  • Table - Add action buttons to table rows

​
Source

  • Template: src/unfold/templates/unfold/components/button.html:1
  • Python classes: src/unfold/layout.py:8-26
  • Button styles: src/unfold/widgets.py:42-54

Build docs developers (and LLMs) love

Get started for freeTalk to us