Setup & Core CRUD basics

Use this guide after Getting Started when your first PowerCRUD list page already renders. It shows how to make that page useful day to day: choose what users see, add filtering and pagination, then improve the table's presentation.

Prerequisites

• A working Django project running Django 5.2 or 6.1.
• Python 3.12 or later.

If you have not yet installed PowerCRUD and its base dependencies, complete the steps in Getting Started first.

1. Finish the basics

Before enabling the richer features, work through the Getting Started guide:

• Install the dependencies and wire up the base template assets you plan to use.
• Complete the required Django wiring, including django_htmx.middleware.HtmxMiddleware.
• Declare your first view and confirm the list/template renders without HTMX extras.
• Expose the view somewhere in your project URLs.

When you can load the plain CRUD view end-to-end, come back here to add the features your screen needs.

2. Wire up URLs

If you followed Getting Started, this is already in place. PowerCRUD uses Neapolitan’s get_urls() helper, so you do not write separate paths for the list, create, detail, edit, and delete views.

# myapp/urls.py
from django.urls import path
from neapolitan.views import Role
from . import views

app_name = "projects"

urlpatterns = [
    *views.ProjectCRUDView.get_urls(),
    path("projects/reports/", views.project_report, name="project-report"),
]

If this screen should expose only some operations, pass the roles you want:

urlpatterns = [
    *views.ProjectCRUDView.get_urls(roles={Role.LIST, Role.DETAIL}),
]

Include the app URLs from your project-level urls.py as usual:

# config/urls.py
from django.urls import include, path

urlpatterns = [
    path("projects/", include("myapp.urls")),
]

For the full background, see Neapolitan’s “URLs and view callables”; PowerCRUD uses the same mechanics.

3. Shape list and detail scopes

Choose list and detail content

Start with the information a user needs to scan in the table. Add detail-only context later; you do not need to configure every surface at once.

For the list

• Leave fields unset, or set it to "__all__", to show every concrete model field.
• Use an explicit list when the table needs only selected fields. That list can also include supported queryset annotation names.
• Use exclude when it is shorter to name what should not appear.
• Add a computed @property through properties. Use "__all__" only when every model property is suitable for a list column.
• Set list_options_enabled = True to give users a Cols chooser. Add default_list_fields when the useful default is a smaller subset of the available columns.

Queryset annotations are read-only list fields. They can filter and sort when the active queryset exposes the same annotation name. They do not belong in form, inline-edit, or bulk-edit field lists.

For the detail view

• The View button uses detail_fields, so this is the place for context you do not need in the table or edit forms.
• detail_fields uses the resolved list fields by default. Set it to "__all__" or an explicit list when the detail page needs more context.
• detail_properties starts empty. Add calculated values here with an explicit list, reuse list properties with "__properties__", or use "__all__" when that is genuinely suitable.
• detail_exclude and detail_properties_exclude let you fine-tune those choices without repeating every field name.

Optional custom buttons

Skip this section until the standard list is working. Use extra_buttons for page-level actions above the table, such as a report, an import, or a summary of selected records. They are not actions on an individual row. The standard configuration API uses dictionaries for these entries.

Use extra_buttons_mode = "dropdown" when several page-level actions would make the toolbar hard to scan. The built-in Create button remains visible because it is not part of extra_buttons. The dropdown trigger is labelled Actions by default; set extra_buttons_dropdown_label when a view needs more specific wording.

Typical uses:

• link to dashboards or reports
• open custom modals
• add list-level utilities that are not tied to a single row

Start with a normal link or endpoint:

extra_buttons = [
    {
        "url_name": "projects:report",
        "text": "Project report",
        "needs_pk": False,
        "display_modal": False,
    },
]

The label can be overridden per view:

extra_buttons_mode = "dropdown"
extra_buttons_dropdown_label = "More"

Optional row actions

Use extra_actions only when a row needs an operation beyond the built-in View, Edit, and Delete controls. These actions belong to your application, so build and secure their endpoints as you would any other Django view. The standard configuration API uses dictionaries for these entries.

For row actions, extra_actions_mode controls which actions stay visible in the row:

• extra_actions_mode = "buttons" renders labelled extra-action buttons beside the compact built-in icon controls.
• extra_actions_mode = "dropdown" keeps the built-in icon controls visible and puts only your extra actions behind a neutral kebab whose accessible name is More actions.
• extra_actions_mode = "all_dropdown" puts every permitted row action behind a compact vertical-ellipsis Actions trigger. The menu is one ordered, labelled list: View, Edit, configured extras in declaration order, then Delete last.
• extra_actions_dropdown_open_upward_bottom_rows = 3 opens the row menu upward for the last three rows on the page. Set it to 0 when every menu should open downward.

The wider-screen default is "dropdown". Set "buttons" when configured extras should remain directly visible beside the built-in actions.

Below 640px, every desktop mode automatically uses the all_dropdown presentation: one Actions kebab containing every permitted native and configured action. The heading also becomes visually compact. This responsive behavior needs no extra setting. Inline Save and Cancel are never moved into the menu.

Optional action icons

An extra_actions dictionary can include trusted inline SVG markup with icon_svg. Keep the SVG in application source code, normally as a named module constant. PowerCRUD renders this value as markup and does not sanitise it, so never build it from request data, database content, or another untrusted source.

TIMELINE_ICON_SVG = """
<svg viewBox="0 0 24 24" fill="none" stroke="currentColor">
    <path stroke-linecap="round" stroke-linejoin="round" d="M4 5h16M4 12h10M4 19h16" />
</svg>
"""

extra_actions = [
    {
        "url_name": "projects:project-timeline",
        "text": "Timeline",
        "needs_pk": True,
        "icon_svg": TIMELINE_ICON_SVG,
    },
]

In extra_actions_mode = "buttons", an icon normally appears beside the text. Set icon_only=True to render only the icon; this requires icon_svg and PowerCRUD supplies the action text as the accessible name and tooltip. In either dropdown mode, entries always retain their visible text. When at least one rendered action in a dropdown has an icon, the first-party packs reserve one shared icon gutter for every entry; a menu with no icons has no empty gutter.

In all_dropdown mode the table heading is visually empty at every width to save space, but its screen-reader name and the trigger's accessible name remain Actions.

When bulk or selection-aware features enable the checkbox column, PowerCRUD pins it to logical start by default. Sticky start actions sit immediately after it; sticky end actions can remain visible at the opposite edge. Selection-column stickiness is not a separate view option.

Start with the smallest useful action:

class AuthorCRUDView(PowerCRUDMixin, CRUDView):
    # ...
    extra_actions = [
        {
            "url_name": "projects:project-timeline",
            "text": "Timeline",
            "needs_pk": True,
            "display_modal": True,
        },
    ]

Reusable action and button declarations

Use the Structured API only when related views repeat the same action with small changes. PowerAction and PowerButton group the same configuration into reusable Python objects, and they can be mixed with dictionaries in one list.

For reusable action patterns, see PowerAction and PowerButton and Structured API Recipes. For the full constructor contract, see PowerAction and PowerButton Reference.

For operation permission, hide versus disable behavior, and backend enforcement boundaries, see Permission-Aware Affordances.

4. Enable UI helpers

Once the basic view works, turn on the built-in enhancements.

Filtering & sorting

class ProjectCRUDView(PowerCRUDMixin, CRUDView):
    # …
    use_htmx = True
    filterset_fields = ["owner", "status", "created_date"]
    default_filterset_fields = ["owner", "status"]

This is the quickest way to add filters. Use the dedicated Filtering guide when you need more than these generated controls.

What happens at a high level:

• With no filterset_fields, the list loads without generated filters. Sorting and pagination still work.
• filterset_fields asks PowerCRUD to build ordinary django-filter controls for those fields.
• Leave default_filterset_fields unset to show every allowed filter. Set it to a smaller subset to keep the rest in Add filter.
• Typed queryset annotations can be filters when the active queryset exposes the same annotate(...) name.
• Sorting stays in the table headers, so users can still share URLs such as /projects/?sort=status.

If a sortable relation column should use something other than the normal default, configure column_sort_fields_override:

class ProjectCRUDView(PowerCRUDMixin, CRUDView):
    # …
    column_sort_fields_override = {
        "owner": "owner__email",
        "customer": "customer__code",
    }

column_sort_fields_override changes only the named columns. Other sortable fields keep their normal ordering.

For the full filtering feature set, including:

• default vs optional filters
• null helpers
• filterset_class precedence
• M2M AND logic
• filter-side dropdown_sort_options and filter_queryset_options
• queryset annotation fields
• HTMX visibility persistence

see Filtering.

Saved favourites are documented separately because they are an optional contrib add-on rather than part of the core filtering contract. See Saved Favourites.

Modals

class ProjectCRUDView(PowerCRUDMixin, CRUDView):
    # …
    use_htmx = True
    use_modal = True

Most screens need only these two settings. Modals depend on HTMX:

• Set use_htmx = True first.
• Set use_modal = True to open create, edit, delete, bulk, and modal-enabled custom actions in the standard PowerCRUD dialog.
• Failed validation stays in that dialog, so users can correct the form without losing their place in the list.

{
    "size": "default",                 # compact, default, wide, extra_wide
    "max_width": None,                  # or a safe CSS length such as "48rem"
    "max_height": "viewport",          # or a safe CSS length
    "scroll": "body",                  # body or modal
    "fullscreen": False,
    "vertical_alignment": "center",    # top or center
}

When the whole view needs more room, set its modal defaults:

class ProjectCRUDView(PowerCRUDMixin, CRUDView):
    # …
    use_htmx = True
    use_modal = True

    modal_presentation = {"size": "wide"}
    bulk_modal_presentation = {"size": "extra_wide"}

An individual modal button, row action, or list-cell link can set its own partial modal_presentation when only that one trigger needs different sizing:

extra_actions = [
    {
        "url_name": "projects:timeline",
        "text": "Timeline",
        "display_modal": True,
        "modal_presentation": {"max_width": "64rem", "vertical_alignment": "top"},
    },
]

Pagination

class ProjectCRUDView(PowerCRUDMixin, CRUDView):
    # …
    paginate_by = 25

PowerCRUD shows 25 rows per page by default. Set paginate_by to another default, or set paginate_by = None only when a view should show every record at once.

• By default, the selector shows 5/10/25/50/100 plus All.
• Set page_size_options = [10, 25, 50] to offer only those finite choices and accept only those values in ?page_size=.
• Set page_size_all_enabled = False to remove All and make ?page_size=all fall back to paginate_by.
• When filters change, the mixin automatically snaps back to page 1 so users do not land on empty pages.
• Pagination works with or without HTMX. With HTMX enabled, only the table/pager fragment updates on navigation.

Record count display

If you want the list view to show a lightweight results summary above the table, enable show_record_count:

class ProjectCRUDView(PowerCRUDMixin, CRUDView):
    # …
    show_record_count = True

PowerCRUD renders a small line above the table. It updates with filtering, sorting, page-size changes, and page navigation.

Examples:

• No active filters: 123 total records
• Active filters without pagination: 27 matching records
• Active filters with pagination: Showing 1-15 of 27 matching records

This is useful when users need quick confirmation that a filter narrowed the queryset as expected, without adding extra noise to the main button toolbar.

When row selection controls are enabled, this area can also offer actions such as Select all matching records. Leave show_bulk_selection_meta = True (the default) to keep that option, even when the record count is off.

5. Make the list easier to read

Use these options after the screen's data and interactions are right. They improve scanability without changing what the screen does.

List heading

If you want the visible list heading to differ from the model’s verbose_name_plural, set view_title on the CRUD view:

class ProjectCRUDView(PowerCRUDMixin, CRUDView):
    # …
    view_title = "Active Client Projects"

view_title changes only the large heading above the list table. It does not affect model verbose names or other UI copy such as button labels.

Helper text

If you want plain-text helper copy directly below the visible list heading, set view_instructions:

class ProjectCRUDView(PowerCRUDMixin, CRUDView):
    # …
    view_instructions = "Use the table below to review and update active projects."

view_instructions adds a small escaped text block directly underneath the heading.

Collapsed screen help

If you want longer screen-level guidance without making the page header heavy, set view_help:

class ProjectCRUDView(PowerCRUDMixin, CRUDView):
    # …
    view_help = {
        "summary": "About this screen",
        "details": (
            "Use this screen to review active projects.\n\n"
            "Inline fields can be edited directly from the table."
        ),
        "color": "info",
    }

view_help renders a collapsed help panel below view_instructions and above the list toolbar. The summary is the one-line clickable bar, and details is plain text. Separate paragraphs with blank lines. Add "default_open": True only when the guidance should start expanded.

Most views should use either view_instructions for a short always-visible sentence or view_help for longer optional guidance. Use both only when the short description and expandable detail carry distinct information.

See Testing and accepting a template pack for the support boundary across packs.

Field labels

PowerCRUD normally uses each model field's verbose_name for display labels. If a view needs an explicit label, use field_labels:

class ProjectCRUDView(PowerCRUDMixin, CRUDView):
    # …
    field_labels = {
        "designated_execution_owner": "DDMS Execution Owner",
    }

Explicit labels render exactly on list headers, the column chooser, generated forms, inline edit labels, display-only form items, and bulk edit labels. If no explicit label is configured, PowerCRUD preserves the model field verbose_name without applying title case, so acronym labels such as "DDMS Execution Owner" stay intact.

Header tooltips

If you want plain-text help tooltips on selected column headers, use column_help_text:

class ProjectCRUDView(PowerCRUDMixin, CRUDView):
    # …
    column_help_text = {
        "owner": "The client or business owner responsible for the project.",
        "display_status": "Calculated status shown for quick triage.",
    }

column_help_text adds an info trigger beside only the configured labels. Sorting still works normally on the header.

Tooltips for table cells

Use a list-cell tooltip when a visible value needs a row-specific explanation that would make the table too busy if shown all the time. Configure list_cell_tooltip_fields as a field-to-method mapping:

• The key is the rendered field or property name, such as "owner".
• The value is the name of a method on the view, such as "get_owner_tooltip".

PowerCRUD calls that method only for visible cells and uses the returned text as the tooltip.

class ProjectCRUDView(PowerCRUDMixin, CRUDView):
    # …
    list_cell_tooltip_fields = {
        "owner": "get_owner_tooltip",
        "display_status": "get_display_status_tooltip",
    }

    def get_owner_tooltip(self, obj, request=None):
        return f"{obj.owner.email} ({obj.owner.team.name})"

    def get_display_status_tooltip(self, obj, request=None):
        return obj.status_explanation

For expensive tooltip hooks, see Lazy Evaluation.

Each method receives the row object and should return plain text, or None when that row should not show a tooltip. Configured names that are not visible in the table are ignored.

Returned list-cell tooltip text may include newline characters for multiple lines. Header-help and other tooltip surfaces remain single-line.

Choose the tooltip that matches the job:

• column_help_text is header help only.
• list_cell_tooltip_fields = {"field": "hook_name"} provides semantic per-cell tooltip text for selected rendered columns.
• Unconfigured cells keep the built-in overflow tooltip behavior when their rendered content is truncated.

When a row-specific tooltip is configured, it replaces the overflow tooltip for that cell. view_instructions, view_help, column_help_text, and list-cell tooltip text are escaped plain text, not HTML.

Links from table cells

If a rendered value should open another page, configure link_fields. The key is the displayed field or property name. For the common internal-link case, the value is simply a Django URL name; use the longer dictionary form only when a link needs extra information:

class ProjectCRUDView(PowerCRUDMixin, CRUDView):
    # …
    list_cell_link_default_open_in = "modal"

    link_fields = {
        # Minimal internal link. Because owner is a relation, PowerCRUD uses
        # obj.owner_id as the pk for reversing crm:owner-detail. Because this
        # view sets list_cell_link_default_open_in, it opens in the modal.
        "owner": "crm:owner-detail",

        # Link this row's own project detail in the shared PowerCRUD modal
        # with per-cell modal sizing. Because reference_code is not a relation,
        # pk_attr defaults to "pk".
        "reference_code": {
            "view_name": "projects:project-detail",
            "modal_presentation": {"size": "extra_wide"},
        },

        # Link a property column to this row's detail view in the current page.
        "display_status": {
            "view_name": "projects:project-detail",
            "pk_attr": "pk",
            "open_in": "current",
        },

        # Static external URL for a rendered property. Browser settings decide
        # tab vs window.
        "is_overdue": {
            "url": "https://docs.example.com/projects",
            "open_in": "new",
        },
    }

The supported shapes are:

• keys are rendered list field/property names
• string values are treated as Django view_name links
• dict values must include exactly one of view_name or url
• dict values may also include pk_attr for view_name links
• dict values may include open_in
• dict values may include modal_presentation only for modal-opening links

list_cell_link_default_open_in sets the view-wide opening style: "current", "new", or "modal". If you omit it, links open in a new browser context. Use "modal" when a drill-in should preserve the current list, or "current" for normal navigation. An individual link's open_in always wins.

pk_attr names the current-row attribute PowerCRUD should use as the pk URL kwarg for a view_name. If you omit it, PowerCRUD uses these defaults:

• relation fields such as owner use <field_name>_id
• non-relation fields and properties use the current row pk

That keeps common links short:

• {"owner": "crm:owner-detail"} means “link the owner column to the related owner detail using owner_id”
• {"reference_code": "projects:project-detail"} means “link the reference_code column to this project row’s own detail using pk”

open_in controls an individual link:

• omitted uses list_cell_link_default_open_in; if that view option is also omitted, PowerCRUD assumes "new"
• "current" opens as a normal same-page anchor
• "new" renders target="_blank" and defaults rel="noopener noreferrer"
• "modal" reuses the view’s existing PowerCRUD modal target and modal-open attributes

If a link requests open_in = "modal" but the view does not use HTMX modals, PowerCRUD falls back to normal current-page navigation.

modal_presentation on a modal list-cell link changes the modal only for that clicked cell. It uses the same per-trigger choices as modal buttons and row actions; for example, set {"size": "extra_wide"} or {"max_width": "64rem"}.

For conditional links or richer metadata, override get_list_cell_link(...):

class ProjectCRUDView(PowerCRUDMixin, CRUDView):
    # …
    link_fields = {
        "owner": "crm:owner-detail",
    }

    def get_list_cell_link(self, obj, field_name, value, *, is_property, request=None):
        if field_name == "display_status" and obj.status_report_url:
            return {
                "url": obj.status_report_url,
                "title": "Open external status report",
                "open_in": "new",
            }
        if field_name == "reference_code":
            return {
                "url": self.safe_reverse("projects:project-detail", kwargs={"pk": obj.pk}),
                "open_in": "modal",
                "modal_presentation": {"size": "extra_wide"},
            }
        if field_name == "owner" and request and not request.user.has_perm("crm.view_owner"):
            return False
        return None

The hook returns one of these values:

• return a dict with at least url to link that cell
• include open_in when the cell should open somewhere other than the view-wide default
• include modal_presentation only with open_in = "modal" for portable per-cell modal sizing
• return None to fall back to link_fields
• return False to suppress link_fields for that cell

Keep these boundaries in mind:

• inline-editable cells are never linked, because inline click-to-edit takes precedence
• if a field appears in both link_fields and inline_edit_fields, PowerCRUD logs a warning and silently skips the link at render time
• the hook applies to fields and properties, not only relations

Column alignment

PowerCRUD chooses a sensible body-cell alignment from the field type. If a short categorical value would scan better centred or right-aligned, override that one column:

class ProjectCRUDView(PowerCRUDMixin, CRUDView):
    # ...
    column_alignments = {
        "status": "center",
        "priority_band": "center",
    }

Use left, center, or right. This changes body cells only. First-party packs centre headers independently, and other columns keep PowerCRUD's usual alignment.

Column widths

Tables often mix short values, such as checkmarks, IDs, dates, and amounts, with names and descriptions. Turn on automatic column sizing to keep the short columns from taking more room than they need and leave more space for the text people read:

class ProjectCRUDView(PowerCRUDMixin, CRUDView):
    # ...
    column_width_policy = "semantic"

With "semantic", PowerCRUD chooses one of three width modes from the field type:

• "compact" keeps automatic IDs and checkmarks as narrow as practical. Long header labels can wrap instead of making the column unnecessarily wide.
• "auto" sizes dates, times, and numbers around their values.
• "bounded" gives descriptive text, relations, computed properties, and other columns without a short-value rule a sensible maximum width.

Queryset annotations use their declared Django output_field, so Boolean, numeric, and temporal annotations receive the same automatic treatment as those model-field types. A computed Python property has no such type metadata; choose a width explicitly when its value is known to be short.

Normally, you can leave those choices to PowerCRUD. Override an individual column only when your application knows better. For example, a short asset code stored in a text field can use the compact treatment:

class ProjectCRUDView(PowerCRUDMixin, CRUDView):
    # ...
    column_width_policy = "semantic"
    column_width_modes = {
        "asset_code": "compact",
    }

You can use "compact", "auto", or "bounded" in column_width_modes whenever an individual column needs a different treatment. Without column_width_policy = "semantic", PowerCRUD keeps its normal general-purpose table sizing.

Using PowerField? Put the same choice on the field declaration:

PowerField("asset_code", column={"width": "compact"})

Column widths affect list layout only. They do not change values, sorting, filtering, or body-cell alignment. See the configuration reference and PowerField reference for the complete option lists.

Row-actions column layout

Wide tables can keep their per-row controls close to the edge where users are working:

class ProjectCRUDView(PowerCRUDMixin, CRUDView):
    # ...
    row_actions_column_position = "start"
    row_actions_column_sticky = True

The two settings are independent. Use "start" or "end" for logical placement and True or False for horizontal pinning. Defaults are "end" and True, keeping row actions at logical end and visible during horizontal scrolling. In LTR pages, start is the left edge; in RTL pages it is the right edge. Set row_actions_column_sticky = False to restore the previous scrolling column.

When row selection is enabled, its checkbox remains the outermost logical-start column. A start-positioned Actions column comes immediately after it, followed by data columns. PowerCRUD preserves that same order in the header, display rows, active inline forms, and HTMX row replacements. Sticky actions stay with their row vertically; only horizontal table scrolling pins them to the configured edge. Both body-level floating row-action menus continue to work without additional JavaScript configuration.

List toolbar layout

By default, the list toolbar follows the rendered table width and keeps action controls at logical start with view controls at logical end. These are independent per-view settings, so each CRUD view can choose its own width and alignment. To keep view controls usable when semantic column sizing produces a compact table, use the PowerCRUD list container width—not the browser viewport—and keep the view-controls group beside the action buttons:

class ProjectCRUDView(PowerCRUDMixin, CRUDView):
    # Opt in to the compact-table-friendly arrangement.
    list_toolbar_width_policy = "container"
    list_toolbar_alignment = "adjacent"

The defaults are list_toolbar_width_policy = "table" and list_toolbar_alignment = "split", preserving the legacy table-aligned arrangement. All four combinations are valid, and controls wrap naturally rather than overflowing on narrow screens.

How dates and times appear in lists

Date, time, and datetime columns use Django's DATE_FORMAT, TIME_FORMAT, and DATETIME_FORMAT settings. DateField shows a date, TimeField shows a time, and DateTimeField shows a date by default.

Set these Django settings explicitly when PowerCRUD should use a particular regional display format:

# settings.py
DATE_FORMAT = "d/m/Y"
TIME_FORMAT = "H:i"
DATETIME_FORMAT = "d/m/Y H:i"

If they are unset, Django uses its own defaults. Set default_datetime_value_format when most datetime columns on one screen should show a time or both date and time. Use column_value_formats for named DateTimeField or typed datetime-annotation overrides:

class ProjectCRUDView(PowerCRUDMixin, CRUDView):
    # ...
    default_datetime_value_format = "datetime"
    column_value_formats = {
        "updated_at": "time",
        "completed_at": "datetime",
    }

The available lower-case modes are date, time, and datetime. DateField accepts only date; TimeField accepts only time; and DateTimeField accepts all three. PowerCRUD validates model fields during setup and typed annotations before rendering. A property or annotation without a known temporal type raises ImproperlyConfigured rather than guessing.

6. Verify the page

Run the development server and open /projects/ (or whatever path you configured). You should see:

• A table listing your model fields (and properties if configured).
• A filter sidebar if you enabled filters.
• Column headers that allow sorting.
• HTMX/Modal behaviour if you turned them on.

If something renders incorrectly, double-check:

• base_template_path is pointing at an actual template.
• django_htmx middleware is installed (for reactive behaviour).
• The view’s fields match real model fields or queryset annotations on the effective queryset.

7. Next steps

• Continue with Forms to learn how PowerCRUD builds forms, how form_class changes the rules, and how contextual display fields, disabled inputs, and dependent dropdowns fit together.
• Then move on to Inline editing to reuse those form rules in HTMX row editing.
• After that, continue to Bulk editing (synchronous) to enable multi-record edit/delete.
• Need more detail on individual settings? See the Configuration reference.