Configuration Options

Complete alphabetical reference of all available configuration options with defaults, accepted values, and descriptions.

Types are shown next to each setting name. Accepted values is the contract for each setting. None means the setting is left unset unless the row says otherwise.

For the mental model behind the option groups, see PowerCRUD Concepts.

Core Configuration

Settings Configuration

All of the following keys live inside the optional POWERCRUD_SETTINGS dict in your Django settings. Every entry has a default; you only override what you need.

Filter controls

Fine-tune what users can filter and how options are presented by combining filterset_fields, default_filterset_fields, filter_queryset_options, dropdown_sort_options, filter_null_fields_exclude, and m2m_filter_and_logic.

default_filterset_fields controls which allowed filters are visible on first render.

• Leave it unset to keep the current behavior and show every allowed filter immediately.
• Set it to a subset to keep the remaining allowed filters hidden behind the Add filter control.
• PowerCRUD validates it against the effective filter names from the bound filter form, not only against raw model field names.
• Hidden optional filters become visible automatically when they carry an active value in the URL.
• Visible optional filters persist through the reserved visible_filters query parameter until the user removes them explicitly.

Nullable auto-generated filters behave differently by field type:

• Nullable ForeignKey and OneToOneField filters keep a single dropdown and add an Empty only option near the top.
• Nullable scalar filters such as CharField, TextField, DateField, TimeField, IntegerField, DecimalField, FloatField, and BooleanField gain a separate companion ... is empty boolean select.
• Companion null controls are rendered immediately after their parent auto-generated filter field in the form.

Auto-generated model fields with choices render as dropdown filters and match the selected value exactly. Text fields without choices use icontains by default. There is no separate declarative setting to change that lookup expression field by field; use filterset_class when you need custom lookup expressions.

Queryset annotation filters

Generated filters may also target queryset annotation names:

from django.db.models import BooleanField, Case, Value, When


class BookQueueView(PowerCRUDMixin, CRUDView):
    model = Book

    def get_queryset(self):
        """Attach the public annotation name used by PowerCRUD config."""
        return super().get_queryset().annotate(
            long_book=Case(
                When(pages__gte=400, then=Value(True)),
                default=Value(False),
                output_field=BooleanField(),
            )
        )

    fields = ["title", "author", "pages", "long_book"]
    filterset_fields = ["author", "long_book"]

Rules:

• The name in fields and filterset_fields must match the public annotate(...) keyword.
• Use output_field on Case, Value, and complex expressions so PowerCRUD can infer the generated filter type.
• Annotation fields are read-only list/filter/sort columns. Do not put them in form_fields, inline_edit_fields, or bulk_fields.
• If you set filterset_class, it takes precedence and PowerCRUD does not auto-generate annotation filters.

filter_null_fields_exclude always matches the original field names listed in filterset_fields.

• Use ["birth_date"], not ["birth_date__isnull"].
• Excluding a nullable scalar field suppresses the generated companion ... is empty control.
• Excluding a nullable relation field suppresses the merged Empty only option.

Example:

filterset_fields = ["owner", "published_date", "status"]
default_filterset_fields = ["owner"]
filter_null_fields_exclude = ["status"]

In that configuration, owner stays visible by default, while published_date and status remain allowed but optional. owner keeps one dropdown with Empty only, published_date gains a separate Published date is empty companion filter when added, and status gets no built-in null helper.

If you want title to use iexact or startswith instead of the generated icontains behavior, move that filter into a custom filterset_class.

Start with the Filtering & sorting walkthrough and the dropdown guidance in Bulk editing (synchronous).

Form controls

Override or refine the automatically generated forms with form_class, form_fields, form_fields_exclude, form_display_fields, form_disabled_fields, and field_queryset_dependencies, and enable Crispy Forms support via use_crispy. See the field/detail setup examples in Setup & Core CRUD basics, the dedicated Forms guide, and the complete view example in reference/complete_example.md.

form_display_fields and form_disabled_fields solve two different problems:

• form_display_fields adds a separate read-only Context block above update forms. Use it for contextual model data, including editable=False fields.
• form_disabled_fields keeps a real form input visible but locked on update forms. Because PowerCRUD uses Django field disabling, submitted tampering is ignored and the existing instance value is preserved. This setting does not lock the same field in create forms or inline editing.

Dependent queryset scoping

Use field_queryset_dependencies for straightforward cases where one selectable child field should be filtered from another form field, or where a queryset-backed field should always be restricted to a fixed subset.

Example:

field_queryset_dependencies = {
    "genres": {
        "static_filters": {"is_active": True},
        "depends_on": ["author"],
        "filter_by": {"authors": "author"},
        "order_by": "name",
        "empty_behavior": "none",
    }
}

Supported keys:

• static_filters Fixed queryset lookups that always apply to the field across regular forms, inline forms, and bulk edit dropdowns.
• depends_on Parent form fields whose values drive the child queryset.
• filter_by Mapping of child queryset lookups to parent form field names.
• order_by Optional ordering applied after filtering.
• empty_behavior "none" hides all child choices until the parent value is available. "all" leaves the queryset unfiltered when the parent value is empty.

Notes:

• Static queryset rules apply to regular create/update forms, inline forms, and bulk edit dropdowns.
• Dynamic dependency rules apply to regular create/update forms and inline forms through the same form pipeline.
• Overriding get_bulk_choices_for_field() bypasses declarative static queryset rules for bulk.
• PowerCRUD resolves parent values from bound form data first, then the current instance, then any initial form values.
• Keep this for simple equality-style filtering on queryset-backed form fields. For complex business rules, continue using a custom form_class or view override.
• filter_by maps child queryset lookups to parent form field names. The left-hand side is the lookup used against the child field queryset, while the right-hand side is the parent form field name.

Common mental model:

field_queryset_dependencies = {
    "child_field": {
        "static_filters": {"is_active": True},
        "depends_on": ["parent_field"],
        "filter_by": {"child_queryset_lookup": "parent_field"},
    }
}

That reads as: “restrict child_field choices first by any fixed filters, then by child_queryset_lookup=<value of parent_field> when a parent-driven rule exists”.

Worked examples:

field_queryset_dependencies = {
    "genres": {
        "depends_on": ["author"],
        "filter_by": {"authors": "author"},
    }
}

field_queryset_dependencies = {
    "cmms_asset": {
        "depends_on": ["cmms_property_asset_type_override"],
        "filter_by": {
            "property_asset_type_override": "cmms_property_asset_type_override",
        },
    }
}

For a full explanation of filter_by, migration from old inline-only configs, and regular-vs-inline behaviour, see Forms.

Header buttons

Use extra_buttons for list-level actions above the table.

extra_buttons_mode controls whether configured list-level buttons render directly in the toolbar or move into a compact overflow menu:

• 'buttons' keeps the default behavior and renders every configured extra button visibly.
• 'dropdown' keeps built-in actions such as Create outside the overflow and moves only configured extra_buttons into a top toolbar Actions menu.

Set extra_buttons_dropdown_label to change that menu's visible and accessible trigger text for a particular view. The label must be a non-empty string and is used only when extra_buttons_mode = "dropdown":

extra_buttons_mode = "dropdown"
extra_buttons_dropdown_label = "More"

Selection-aware buttons can opt into the current persisted PowerCRUD selection:

extra_buttons_mode = "dropdown"

extra_buttons = [
    {
        "url_name": "projects:summary-help",
        "text": "Summary Help",
        "display_modal": True,
        "refresh_list_on_modal_close": True,
        "modal_presentation": {"size": "wide"},
    },
    {
        "url_name": "projects:selected-summary",
        "text": "Selected Summary",
        "display_modal": True,
        "uses_selection": True,
        "selection_min_count": 1,
        "selection_min_behavior": "disable",
        "selection_min_reason": "Select at least one row first.",
        "permission_check": "can_view_project_report",
        "permission_behavior": "hide",
    },
]

Notes:

• uses_selection defaults to False.
• selection_min_count defaults to 0.
• selection_min_behavior accepts 'allow' or 'disable' and defaults to 'allow'.
• modal_presentation is only used when display_modal=True; it merges with the view presentation while that button's modal is open. Omit it when the button should use the default dialog.
• refresh_list_on_modal_close is only used when display_modal=True; prefer HX-Trigger: {"refreshTable": true} when the endpoint knows it changed data.
• When uses_selection=True, the button endpoint should use the current persisted PowerCRUD selection.
• clear_selection_on_success defaults to True when uses_selection=True and False otherwise. PowerCRUD clears the persisted selection after the button's successful HTMX request completes; failed requests leave the selection intact. Set clear_selection_on_success=False for summary or preview buttons that should preserve the user's selection.
• A selection-aware extra_buttons entry can render row selection controls even when bulk_fields = [] and bulk_delete = False.
• Set extra_button_selection_controls_disabled = True if the button uses selected rows, but this list should not show checkboxes just because of that button.
• This is mainly useful when the selected rows come from somewhere else, or when the page has its own custom way to choose rows. Bulk edit and bulk delete still show checkboxes because they need them.
• permission or permission_check hides or disables the button before selection-state checks run. permission_behavior defaults to "hide".
• The endpoint should still validate selection size, permissions, and lock rules server-side.

Row actions

Use extra_actions to add per-row actions beyond the built-in View, Edit, and Delete links. Entries may be Base API dictionaries or PowerAction declarations from powercrud.actions.

extra_actions_mode controls how those extra row actions are displayed:

• 'buttons' keeps compact built-in icon controls visible and renders configured extra actions as labelled buttons.
• 'dropdown' keeps the built-in icon controls visible and moves only extra_actions behind a neutral vertical-ellipsis trigger whose accessible name is More actions.
• 'all_dropdown' replaces the visible row controls with one neutral vertical-ellipsis Actions trigger. Its labelled menu order is View, Edit, configured extras in declaration order, then Delete last.

Below 640px, the first-party packs collapse all three modes to the all_dropdown presentation. The single Actions kebab contains every permitted native and configured action in canonical order. This is a responsive default rather than another configuration value; inline Save and Cancel remain visible while editing.

The all-actions trigger and its tooltip have the accessible name Actions. The table's visual Actions heading is omitted in this compact mode, while a screen-reader-only heading preserves the column name. Inline Save and Cancel remain visible while a row is being edited.

The action column itself has two independent layout settings:

row_actions_column_position = "start"
row_actions_column_sticky = True

position is logical rather than physical, so it follows LTR/RTL direction. Selection checkboxes always remain the outermost start column; start-positioned actions follow them. Stickiness applies only while the table scrolls horizontally and is carried through the header, normal rows, inline edit controls, and HTMX-returned replacement rows. The default combination is "end" plus True.

Example:

extra_actions_mode = "dropdown"
extra_actions_dropdown_open_upward_bottom_rows = 3

extra_actions = [
    {
        "url_name": "sample:author-detail",
        "text": "View Again",
        "needs_pk": True,
        "display_modal": True,
        "permission_check": "can_view_author_again",
        "permission_behavior": "hide",
        "hidden_if": "should_hide_view_again",
        "hidden_if_mode": "lazy",
        "disabled_state": "get_view_again_disabled_state",
        "disabled_state_mode": "lazy",
        "refresh_list_on_modal_close": True,
        "modal_presentation": {"size": "extra_wide"},
    },
]

Notes:

• The default is 'dropdown': built-in actions remain visible while configured extras move behind the kebab. Set 'buttons' to restore the previous wider-screen presentation.
• extra_actions_mode controls row-action presentation only; it does not affect top-of-page extra_buttons.
• In either dropdown mode, configured button_class values do not colour menu entries. They still apply to visible configured extras in 'buttons' mode.
• icon_svg accepts trusted inline SVG markup for a configured action. Define it as a named application-source constant and never derive it from request, database, or other untrusted data. icon_only defaults to False, requires icon_svg, and affects direct buttons only; dropdown entries always retain their visible label.
• The first-party packs render View, Edit, and both kebab scopes as quiet neutral controls. Delete alone retains restrained destructive colour. Menus use neutral rows, reserve an icon gutter only when at least one currently rendered action has an icon, and add a divider before Delete only when another visible item precedes it.
• Selection checkboxes are a system column pinned to logical start by default; this is not separately parameterised. Sticky logical-start actions sit immediately after selection, while sticky logical-end actions remain pinned at the opposite edge.
• To restore the previous scrolling action column, set row_actions_column_sticky = False.
• Permission-hidden standard actions are omitted. Disabled reasons, modal behavior, HTMX behavior, history, guards, lazy state, and refresh-on-close metadata are preserved.
• extra_actions_dropdown_open_upward_bottom_rows counts from the bottom of the currently rendered rows after filtering and pagination.
• Set extra_actions_dropdown_open_upward_bottom_rows = 0 to keep every dropdown opening downward.
• modal_presentation is only used when display_modal=True; it merges with the view presentation while this row action's modal is open.
• refresh_list_on_modal_close is only used when display_modal=True; prefer HX-Trigger: {"refreshTable": true} when the endpoint knows it changed data.
• hidden_if is an optional view method name with signature (obj, request) -> bool. Return True to omit the action for that row. Hidden actions are removed before disabled hooks are evaluated.
• Set hidden_if_mode = "lazy" only in extra_actions_mode = "dropdown" or "all_dropdown" when the row relevance check is expensive and should be resolved when the row menu opens. Button-mode actions keep eager hidden-if evaluation.
• disabled_state is a single-hook alternative to disabled_if / disabled_reason. Return a non-empty string to disable the action and show that string as the reason; return None, False, or an empty string to keep it enabled.
• Set disabled_state_mode = "lazy" only in extra_actions_mode = "dropdown" or "all_dropdown" when the disabled reason is expensive to calculate and should be resolved when the row menu opens. Button-mode actions keep eager disabled-state evaluation.
• permission or permission_check hides or disables the action before hidden_if and disabled_state run. permission_behavior defaults to "hide".
• disabled_if and disabled_reason are deprecated view method names used to disable a row action based on the current object and request. Use disabled_state instead.
• Do not combine disabled_state with disabled_if or disabled_reason on the same action.
• Use hidden_if when an action is not applicable for a row. Use disabled_state when the action is applicable but unavailable and needs an explanatory reason.
• lock_sensitive remains available when an action should also disable under PowerCRUD's existing lock/blocked-row state.

See Permission-Aware Affordances for built-in Create/Detail/Edit/Delete permission hooks and backend enforcement boundaries.

Searchable select enhancement

PowerCRUD enhances eligible select dropdowns with Tom Select when searchable_selects = True (default).

• Applies to regular create/update forms, inline row forms, bulk edit form selects, and filter form selects.
• Single-select fields are enhanced as searchable dropdowns.
• Inline single-selects focus when their row enters edit mode, but the dropdown stays closed until the user clicks or types.
• Multi-select fields use the selected pack's standard variant on normal forms, filters, and bulk forms, and its compact variant inline.
• Standard and compact multiselects keep selected options visible with checked state, allow click-to-toggle while open, and provide clear-all.
• Boolean-style selects remain native controls.
• Preserves normal Django single- and multi-value POST semantics through the underlying <select>.
• The selected pack owns enhancement presentation and styling; application enable/disable intent remains authoritative.

See Forms, Inline editing, Filtering, and Bulk editing for surface-specific behaviour.

Per-field opt-out is available via a view hook:

class BookCRUDView(PowerCRUDMixin, CRUDView):
    searchable_selects = True

    def get_searchable_select_enabled_for_field(
        self, field_name: str, bound_field=None
    ) -> bool:
        return field_name != "author"

Inline dependency controls

Use field_queryset_dependencies as the primary declaration when one inline field needs another field to be refreshed in the same row. PowerCRUD derives inline dependency wiring from that shared config automatically.

Example:

field_queryset_dependencies = {
    "genres": {
        "depends_on": ["author"],
        "filter_by": {"authors": "author"},
    }
}

Notes:

• The child field must also be present in inline_edit_fields.
• Parent fields listed in depends_on must be inline-editable too.
• PowerCRUD handles the frontend refresh, widget swap, and child queryset restriction when the dependency is declared in field_queryset_dependencies.
• PowerCRUD uses the standard ...-inline-dependency endpoint automatically.
• Older inline-only dependency config is ignored. Move any remaining business rules into field_queryset_dependencies.

Migration sketch:

field_queryset_dependencies = {
    "cmms_asset": {
        "depends_on": ["cmms_property_asset_type_override"],
        "filter_by": {
            "property_asset_type_override": "cmms_property_asset_type_override",
        },
    }
}

See Forms for a fuller worked example.

Notes

• Required settings: Only model and base_template_path are required.
• Auto-detection: use_crispy auto-detects whether crispy_forms is installed; everything else is opt-in.
• Dependencies: Bulk operations require both use_htmx = True and use_modal = True.
• Detail permissions: Override has_power_detail_permission(request, obj) when the current user should not see the built-in Detail/View row action or call the PowerCRUD-owned detail endpoint.
• Bulk permissions: bulk_fields and bulk_delete configure the operation surface. Override has_power_bulk_update_permission(request) or has_power_bulk_delete_permission(request) when the current user should not see or call those PowerCRUD-owned bulk operations.
• Duplicate entries: Supported list-style config options quietly remove duplicates and keep the first occurrence.
• Field shortcuts: Use '__all__' for all fields, '__fields__' to reference the fields setting.
• Property shortcuts: Use '__all__' for all properties, '__properties__' to reference the properties setting.