Keyword options

Every component takes its configuration as keyword arguments, and every set of them is declared as a TypedDict that the factory methods unpack (**kwargs: Unpack[_ModelFormOptionInputs]). That is what makes an unknown keyword a TypeError and a known one an editor completion — and it is where each option's own description lives, which is why these otherwise private types are documented here.

The names begin with an underscore because they are not meant to be imported or subclassed. Read them as the option list of the component they belong to.

Two sources for the same option

Most of these can also be set on the model's Meta class, where the answer belongs to the model rather than to one view of it — a keyword argument then wins over Meta. See Field types.

Form

_ModelFormOptionInputs

Kwarg Options for the ModelForm class. Chrome (title, description, save/refresh buttons) belongs to EditFormWrapper.

Source code in niceview/modelform.py

class _ModelFormOptionInputs(typing_extensions.TypedDict, total=False):
    """
    Kwarg Options for the ModelForm class.
    Chrome (title, description, save/refresh buttons) belongs to EditFormWrapper.
    """
    include: list[str] | str
    """Fields to show; '__all__' (default) or a list of names."""
    exclude: list[str] | str
    """Fields to hide; combines with include."""
    field_infos: dict[str, FieldInfo]
    """Per-field FieldInfo overrides, by field name."""
    profile: str | None
    """Named field layout profile from Meta.profiles (e.g. 'summary', 'detail'). Defaults to
    Meta.default_profile when omitted."""

    layout: list
    """Inline field layout: a nested list of field names — rows/columns, '# Title' cards,
    '@name' places an action. Same notation as a Meta.profiles entry."""

    actions: dict[str, 'FormAction']
    """The form's action buttons, by name: buttons that are not fields ('Test connection').
    Placed in the layout as '@name', or by hand with render_action('name')."""

    base_props: str
    """Quasar props applied to every field of this form (e.g. 'outlined dense'). Additive: the
    field's own props are merged on top, per key, so a field can add or change a single prop."""

    default_classes: str
    """CSS classes for every field of this form that brings none of its own (e.g. 'w-full').
    A fallback, not a base: any classes on the field or in the layout replace it wholesale."""

    autosave: bool
    """Whether to automatically save the form on field change. Defaults to False (OFF)."""

    local_tz: str | None
    """Local timezone name for datetime display (e.g. 'Europe/Berlin'). Defaults to None (system local timezone)."""

    on_change: Handler[FieldChangeEventArguments]
    """Callback to execute when value changes. To reduce the number of change events, fields like ui.input or ui.number also have to loose focus (blur)."""

    required_marker: str | None
    """Appended to the label of a required field. Defaults to ' *'; None renders no marker."""

    required_message: str
    """Validation message for an empty required field. Defaults to 'Required'."""

    description_as: 'DescriptionTarget'
    """Where a field's pydantic `description` shows: 'tooltip' (default), 'hint', or None. An
    explicit `hint`/`tooltip` on the field always wins."""

    chrome_style: 'ChromeStyle | None'
    """Look of the section titles of this form's layout. Replaces the application-wide default
    of niceview.style.set_chrome_style() wholesale — derive it with ChromeStyle.derived()."""

    chrome_text: 'ChromeText | None'
    """Texts of this form. Replaces the application-wide default of
    niceview.text.set_chrome_text() wholesale — derive it with ChromeText.derived()."""

include instance-attribute

include: list[str] | str

Fields to show; 'all' (default) or a list of names.

exclude instance-attribute

exclude: list[str] | str

Fields to hide; combines with include.

field_infos instance-attribute

field_infos: dict[str, FieldInfo]

Per-field FieldInfo overrides, by field name.

profile instance-attribute

profile: str | None

Named field layout profile from Meta.profiles (e.g. 'summary', 'detail'). Defaults to Meta.default_profile when omitted.

layout instance-attribute

layout: list

Inline field layout: a nested list of field names — rows/columns, '# Title' cards, '@name' places an action. Same notation as a Meta.profiles entry.

actions instance-attribute

actions: dict[str, FormAction]

The form's action buttons, by name: buttons that are not fields ('Test connection'). Placed in the layout as '@name', or by hand with render_action('name').

base_props instance-attribute

base_props: str

Quasar props applied to every field of this form (e.g. 'outlined dense'). Additive: the field's own props are merged on top, per key, so a field can add or change a single prop.

default_classes instance-attribute

default_classes: str

CSS classes for every field of this form that brings none of its own (e.g. 'w-full'). A fallback, not a base: any classes on the field or in the layout replace it wholesale.

autosave instance-attribute

autosave: bool

Whether to automatically save the form on field change. Defaults to False (OFF).

local_tz instance-attribute

local_tz: str | None

Local timezone name for datetime display (e.g. 'Europe/Berlin'). Defaults to None (system local timezone).

on_change instance-attribute

on_change: Handler[FieldChangeEventArguments]

Callback to execute when value changes. To reduce the number of change events, fields like ui.input or ui.number also have to loose focus (blur).

required_marker instance-attribute

required_marker: str | None

Appended to the label of a required field. Defaults to ' *'; None renders no marker.

required_message instance-attribute

required_message: str

Validation message for an empty required field. Defaults to 'Required'.

description_as instance-attribute

description_as: DescriptionTarget

Where a field's pydantic description shows: 'tooltip' (default), 'hint', or None. An explicit hint/tooltip on the field always wins.

chrome_style instance-attribute

chrome_style: ChromeStyle | None

Look of the section titles of this form's layout. Replaces the application-wide default of niceview.style.set_chrome_style() wholesale — derive it with ChromeStyle.derived().

chrome_text instance-attribute

chrome_text: ChromeText | None

Texts of this form. Replaces the application-wide default of niceview.text.set_chrome_text() wholesale — derive it with ChromeText.derived().

_EditFormWrapperInputs

Source code in niceview/editwrapper.py

class _EditFormWrapperInputs(typing_extensions.TypedDict, total=False):
    title: str | None
    """Form title; omitted/None/'' all show none — a form edits one item, so nothing is
    auto-generated. Defaults from Meta.title."""
    description: str | None
    """Markdown below the title row. Defaults from Meta.description."""
    save_button: str | None
    """Save button label; '' for icon-only, None hides it. Shown by default when there's an
    adapter (from_json/from_adapter); suppressed entirely by autosave."""
    refresh_button: str | None
    """Refresh button label; '' for icon-only, None hides it. Shown by default when there's an
    adapter (from_json/from_adapter)."""
    chrome_actions: dict[str, 'FormAction']
    """The application's own buttons in the title row, by name, left of Refresh and Save. Same
    FormAction as the form's `actions` — the one that is placed in the layout as '@name'."""
    chrome_style: ChromeStyle | None
    """Look of the title row and its buttons. Replaces the application-wide default of
    niceview.style.set_chrome_style() wholesale — derive it with ChromeStyle.derived().
    Passed on to the wrapped ModelForm, whose section titles it styles too."""
    chrome_text: ChromeText | None
    """Texts of the tooltips and notifications. Replaces the application-wide default of
    niceview.text.set_chrome_text() wholesale — derive it with ChromeText.derived()."""
    place: Place
    """Where this wrapper's buttons sit in the chrome cascade: 'toolbar' (default) for a wrapper
    of its own, 'form' for one embedded in a form."""

title instance-attribute

title: str | None

Form title; omitted/None/'' all show none — a form edits one item, so nothing is auto-generated. Defaults from Meta.title.

description instance-attribute

description: str | None

Markdown below the title row. Defaults from Meta.description.

save_button instance-attribute

save_button: str | None

Save button label; '' for icon-only, None hides it. Shown by default when there's an adapter (from_json/from_adapter); suppressed entirely by autosave.

refresh_button instance-attribute

refresh_button: str | None

Refresh button label; '' for icon-only, None hides it. Shown by default when there's an adapter (from_json/from_adapter).

chrome_actions instance-attribute

chrome_actions: dict[str, FormAction]

The application's own buttons in the title row, by name, left of Refresh and Save. Same FormAction as the form's actions — the one that is placed in the layout as '@name'.

chrome_style instance-attribute

chrome_style: ChromeStyle | None

Look of the title row and its buttons. Replaces the application-wide default of niceview.style.set_chrome_style() wholesale — derive it with ChromeStyle.derived(). Passed on to the wrapped ModelForm, whose section titles it styles too.

chrome_text instance-attribute

chrome_text: ChromeText | None

Texts of the tooltips and notifications. Replaces the application-wide default of niceview.text.set_chrome_text() wholesale — derive it with ChromeText.derived().

place instance-attribute

place: Place

Where this wrapper's buttons sit in the chrome cascade: 'toolbar' (default) for a wrapper of its own, 'form' for one embedded in a form.

Grid

_ModelGridOptionInputs

Keyword options for ModelGrid and its factory methods.

Source code in niceview/modelgrid.py

class _ModelGridOptionInputs(typing_extensions.TypedDict, total=False):
    """Keyword options for ModelGrid and its factory methods."""
    include: list[str] | str
    """Fields to show; '__all__' (default) or a list of names."""
    exclude: list[str] | str
    """Fields to hide; combines with include."""
    field_infos: dict[str, FieldInfo]
    """Per-field FieldInfo overrides, by field name."""
    profile: str | None
    """Named field layout profile from Meta.profiles (e.g. 'summary', 'detail'). Defaults to
    Meta.default_profile when omitted."""
    local_tz: str | None
    """Timezone for datetime column display (e.g. 'Europe/Berlin'), like ModelForm's."""

    theme: str
    """ag-grid theme name, e.g. 'ag-theme-balham'."""
    auto_size_columns: bool
    """Auto-size columns to fit their content."""
    defaultColDef: dict
    """ag-grid defaultColDef, merged into every column."""
    rowSelection: Literal[None, 'single', 'multiple']
    """ag-grid row selection mode."""
    cell_renderers: dict[str, Callable[[Any], str]]
    """Per-field value -> display-string converters, by field name."""
    html_fields: list[str]
    """Field names whose cell_renderers output is raw HTML, not plain text — translated to
    ag-grid's html_columns at render(). Without a cell_renderers entry, the raw value renders
    as HTML verbatim."""

include instance-attribute

include: list[str] | str

Fields to show; 'all' (default) or a list of names.

exclude instance-attribute

exclude: list[str] | str

Fields to hide; combines with include.

field_infos instance-attribute

field_infos: dict[str, FieldInfo]

Per-field FieldInfo overrides, by field name.

profile instance-attribute

profile: str | None

Named field layout profile from Meta.profiles (e.g. 'summary', 'detail'). Defaults to Meta.default_profile when omitted.

local_tz instance-attribute

local_tz: str | None

Timezone for datetime column display (e.g. 'Europe/Berlin'), like ModelForm's.

theme instance-attribute

theme: str

ag-grid theme name, e.g. 'ag-theme-balham'.

auto_size_columns instance-attribute

auto_size_columns: bool

Auto-size columns to fit their content.

defaultColDef instance-attribute

defaultColDef: dict

ag-grid defaultColDef, merged into every column.

rowSelection instance-attribute

rowSelection: Literal[None, 'single', 'multiple']

ag-grid row selection mode.

cell_renderers instance-attribute

cell_renderers: dict[str, Callable[[Any], str]]

Per-field value -> display-string converters, by field name.

html_fields instance-attribute

html_fields: list[str]

Field names whose cell_renderers output is raw HTML, not plain text — translated to ag-grid's html_columns at render(). Without a cell_renderers entry, the raw value renders as HTML verbatim.

_EditGridWrapperInputs

Source code in niceview/editwrapper.py

class _EditGridWrapperInputs(typing_extensions.TypedDict, total=False):
    title: str | None
    """Title above the grid; omitted or None auto-generates '{ItemType} List', '' shows none,
    any other string is used verbatim. Defaults from Meta.title_plural (the collection heading)
    when this kwarg is not passed — never from the singular Meta.title."""
    description: str | None
    """Markdown below the title row. Defaults from Meta.description when not passed."""
    on_add: ActionHandler | None
    """Replaces the default Add action (create item_type() and open the create dialog). Sync or
    async — an async handler can ask for input via util.input_dialog() before creating anything."""
    delete_button: str | None
    """Delete button label; '' for icon-only (default), None hides it."""
    add_button: str | None
    """Add button label; '' for icon-only (default), None hides it."""
    edit_button: str | None
    """Edit button label; '' for icon-only (default), None hides it — the default for an
    inline-editable grid, which needs no separate dialog."""
    refresh_button: str | None
    """Refresh button label; '' for icon-only (default when there's an adapter to reload from),
    None hides it."""
    chrome_actions: dict[str, FormAction]
    """The application's own buttons in the title row, by name, left of niceview's own. Same
    FormAction as a form's `actions` — its `on_click` gets a GridActionEventArguments here."""
    chrome_style: ChromeStyle | None
    """Look of the title row and its buttons. Replaces the application-wide default of
    niceview.style.set_chrome_style() wholesale — derive it with ChromeStyle.derived()."""
    chrome_text: ChromeText | None
    """Texts of the tooltips, dialogs and notifications. Replaces the application-wide default
    of niceview.text.set_chrome_text() wholesale — derive it with ChromeText.derived()."""
    place: Place
    """Where this wrapper's buttons sit in the chrome cascade: 'toolbar' (default) for a wrapper
    of its own, 'form' for one embedded in a form."""
    search: bool
    """Show a free-text search box in the title row, filtering grid rows across all columns
    (ag-grid's client-side quick filter) as the user types. Off by default."""

title instance-attribute

title: str | None

Title above the grid; omitted or None auto-generates '{ItemType} List', '' shows none, any other string is used verbatim. Defaults from Meta.title_plural (the collection heading) when this kwarg is not passed — never from the singular Meta.title.

description instance-attribute

description: str | None

Markdown below the title row. Defaults from Meta.description when not passed.

on_add instance-attribute

on_add: ActionHandler | None

Replaces the default Add action (create item_type() and open the create dialog). Sync or async — an async handler can ask for input via util.input_dialog() before creating anything.

delete_button instance-attribute

delete_button: str | None

Delete button label; '' for icon-only (default), None hides it.

add_button instance-attribute

add_button: str | None

Add button label; '' for icon-only (default), None hides it.

edit_button instance-attribute

edit_button: str | None

Edit button label; '' for icon-only (default), None hides it — the default for an inline-editable grid, which needs no separate dialog.

refresh_button instance-attribute

refresh_button: str | None

Refresh button label; '' for icon-only (default when there's an adapter to reload from), None hides it.

chrome_actions instance-attribute

chrome_actions: dict[str, FormAction]

The application's own buttons in the title row, by name, left of niceview's own. Same FormAction as a form's actions — its on_click gets a GridActionEventArguments here.

chrome_style instance-attribute

chrome_style: ChromeStyle | None

Look of the title row and its buttons. Replaces the application-wide default of niceview.style.set_chrome_style() wholesale — derive it with ChromeStyle.derived().

chrome_text instance-attribute

chrome_text: ChromeText | None

Texts of the tooltips, dialogs and notifications. Replaces the application-wide default of niceview.text.set_chrome_text() wholesale — derive it with ChromeText.derived().

place instance-attribute

place: Place

Where this wrapper's buttons sit in the chrome cascade: 'toolbar' (default) for a wrapper of its own, 'form' for one embedded in a form.

search instance-attribute

search: bool

Show a free-text search box in the title row, filtering grid rows across all columns (ag-grid's client-side quick filter) as the user types. Off by default.

List and drill-down

_ModelListOptionInputs

Keyword options for ModelList and its factory methods.

Source code in niceview/modellist.py

class _ModelListOptionInputs(typing_extensions.TypedDict, total=False):
    """Keyword options for ModelList and its factory methods."""
    include: list[str] | str
    """Fields to show; '__all__' (default) or a list of names."""
    exclude: list[str] | str
    """Fields to hide; combines with include."""
    field_infos: dict[str, FieldInfo]
    """Per-field FieldInfo overrides, by field name."""
    profile: str | None
    """Named field layout profile from Meta.profiles (e.g. 'summary', 'detail'). Defaults to
    Meta.default_profile when omitted."""
    local_tz: str | None
    """Timezone for datetime display (e.g. 'Europe/Berlin'), like ModelForm's."""
    title_field: str | None
    """Field shown as each row's title; the first visible field if omitted."""
    subtitle_fields: list[str] | None
    """Fields shown as each row's subtitle; the next two visible fields if omitted."""
    chrome_style: ChromeStyle | None
    """Look of the list and its rows. Replaces the application-wide default of
    niceview.style.set_chrome_style() wholesale — derive it with get_chrome_style().replace()."""

include instance-attribute

include: list[str] | str

Fields to show; 'all' (default) or a list of names.

exclude instance-attribute

exclude: list[str] | str

Fields to hide; combines with include.

field_infos instance-attribute

field_infos: dict[str, FieldInfo]

Per-field FieldInfo overrides, by field name.

profile instance-attribute

profile: str | None

Named field layout profile from Meta.profiles (e.g. 'summary', 'detail'). Defaults to Meta.default_profile when omitted.

local_tz instance-attribute

local_tz: str | None

Timezone for datetime display (e.g. 'Europe/Berlin'), like ModelForm's.

title_field instance-attribute

title_field: str | None

Field shown as each row's title; the first visible field if omitted.

subtitle_fields instance-attribute

subtitle_fields: list[str] | None

Fields shown as each row's subtitle; the next two visible fields if omitted.

chrome_style instance-attribute

chrome_style: ChromeStyle | None

Look of the list and its rows. Replaces the application-wide default of niceview.style.set_chrome_style() wholesale — derive it with get_chrome_style().replace().

_DrillDownWrapperOptionInputs

Keyword options for DrillDownWrapper and its factory methods.

Source code in niceview/drilldown.py

class _DrillDownWrapperOptionInputs(typing_extensions.TypedDict, total=False):
    """Keyword options for DrillDownWrapper and its factory methods."""
    title: str | None
    """List title; None auto-generates '{ItemType} List', '' hides it. Defaults to
    Meta.title_plural; the detail view always shows the item's own title instead."""
    description: str | None
    """Markdown below the title row, in both views. Defaults to Meta.description."""
    item_title_field: str | None
    """Field shown as the detail title; auto-detected (first visible field) if omitted."""
    item_subtitle_fields: list[str] | None
    """Fields shown as list-row subtitles; the next two visible fields if omitted."""
    title_field: str | None
    """Alias of item_title_field (the name ModelList uses); item_title_field wins if both given."""
    subtitle_fields: list[str] | None
    """Alias of item_subtitle_fields (the name ModelList uses)."""
    add_button: str | None
    """Add button label; '' for icon-only (default), None hides it."""
    delete_button: str | None
    """Delete button label; '' for icon-only (default), None hides it."""
    back_button: str | None
    """Back button label; '' for icon-only (default). None omits it — the detail view then
    needs its own way back."""
    search: bool
    """Show a free-text search box in the list view's title row, left of list_actions/Add,
    filtering rows across all visible fields (client-side) as the user types. Off by default;
    hidden in the detail view."""
    list_actions: dict[str, FormAction]
    """Buttons in the list view's title row, left of Add; hidden in the detail view. on_click
    gets a DrillDownListActionEventArguments (no key/item), and requires_valid is rejected."""
    detail_actions: dict[str, FormAction]
    """Buttons in the detail view's title row, left of Delete; hidden in the list view. on_click
    gets a DrillDownActionEventArguments with the item on screen; chrome_actions is an alias
    (detail_actions wins if both given)."""
    chrome_actions: dict[str, FormAction]
    """Deprecated alias of detail_actions, kept for backward compatibility."""
    chrome_style: ChromeStyle | None
    """Look of the title row, its buttons and the list rows. Replaces the application-wide
    default of niceview.style.set_chrome_style() wholesale — derive it with ChromeStyle.derived()."""
    chrome_text: ChromeText | None
    """Texts of the tooltips, dialogs and notifications. Replaces the application-wide default
    of niceview.text.set_chrome_text() wholesale — derive it with ChromeText.derived()."""
    place: Place
    """Where this wrapper's buttons sit in the chrome cascade: 'toolbar' (default) for a wrapper
    of its own, 'form' for one embedded in a form."""
    on_add: ActionHandler | None
    """Replaces the default Add action (create item_type() and open it). Sync or async — an
    async handler can ask for a name via util.input_dialog() before creating anything."""
    on_back: ActionHandler | None
    """Shows a Back button in the list view too (for nesting) and runs on its click. Sync or
    async — an async handler can confirm via util.confirm_dialog() before leaving."""
    render_list_item: ListItemRenderer | None
    """Custom renderer for one list row, replacing the default ModelList row."""
    render_list_container: ListContainerRenderer | None
    """Wraps the rendered rows in a custom container, e.g. for make_sortable."""
    render_detail: DetailRenderer | None
    """Custom renderer for the detail view, replacing the default autosaving form."""
    # ModelList options forwarded when render_list_item is not set:
    include: list[str] | str
    """Fields to show; forwarded to ModelList when render_list_item is not set."""
    exclude: list[str] | str
    """Fields to hide; forwarded to ModelList when render_list_item is not set."""
    field_infos: dict[str, FieldInfo]
    """Per-field FieldInfo overrides; forwarded to ModelList when render_list_item is not set."""
    profile: str | None
    """Named field layout profile from Meta.profiles; forwarded when render_list_item is not set.
    Defaults to Meta.default_profile when omitted."""

title instance-attribute

title: str | None

List title; None auto-generates '{ItemType} List', '' hides it. Defaults to Meta.title_plural; the detail view always shows the item's own title instead.

description instance-attribute

description: str | None

Markdown below the title row, in both views. Defaults to Meta.description.

item_title_field instance-attribute

item_title_field: str | None

Field shown as the detail title; auto-detected (first visible field) if omitted.

item_subtitle_fields instance-attribute

item_subtitle_fields: list[str] | None

Fields shown as list-row subtitles; the next two visible fields if omitted.

title_field instance-attribute

title_field: str | None

Alias of item_title_field (the name ModelList uses); item_title_field wins if both given.

subtitle_fields instance-attribute

subtitle_fields: list[str] | None

Alias of item_subtitle_fields (the name ModelList uses).

add_button instance-attribute

add_button: str | None

Add button label; '' for icon-only (default), None hides it.

delete_button instance-attribute

delete_button: str | None

Delete button label; '' for icon-only (default), None hides it.

back_button instance-attribute

back_button: str | None

Back button label; '' for icon-only (default). None omits it — the detail view then needs its own way back.

search instance-attribute

search: bool

Show a free-text search box in the list view's title row, left of list_actions/Add, filtering rows across all visible fields (client-side) as the user types. Off by default; hidden in the detail view.

list_actions instance-attribute

list_actions: dict[str, FormAction]

Buttons in the list view's title row, left of Add; hidden in the detail view. on_click gets a DrillDownListActionEventArguments (no key/item), and requires_valid is rejected.

detail_actions instance-attribute

detail_actions: dict[str, FormAction]

Buttons in the detail view's title row, left of Delete; hidden in the list view. on_click gets a DrillDownActionEventArguments with the item on screen; chrome_actions is an alias (detail_actions wins if both given).

chrome_actions instance-attribute

chrome_actions: dict[str, FormAction]

Deprecated alias of detail_actions, kept for backward compatibility.

chrome_style instance-attribute

chrome_style: ChromeStyle | None

Look of the title row, its buttons and the list rows. Replaces the application-wide default of niceview.style.set_chrome_style() wholesale — derive it with ChromeStyle.derived().

chrome_text instance-attribute

chrome_text: ChromeText | None

Texts of the tooltips, dialogs and notifications. Replaces the application-wide default of niceview.text.set_chrome_text() wholesale — derive it with ChromeText.derived().

place instance-attribute

place: Place

Where this wrapper's buttons sit in the chrome cascade: 'toolbar' (default) for a wrapper of its own, 'form' for one embedded in a form.

on_add instance-attribute

on_add: ActionHandler | None

Replaces the default Add action (create item_type() and open it). Sync or async — an async handler can ask for a name via util.input_dialog() before creating anything.

on_back instance-attribute

on_back: ActionHandler | None

Shows a Back button in the list view too (for nesting) and runs on its click. Sync or async — an async handler can confirm via util.confirm_dialog() before leaving.

render_list_item instance-attribute

render_list_item: ListItemRenderer | None

Custom renderer for one list row, replacing the default ModelList row.

render_list_container instance-attribute

render_list_container: ListContainerRenderer | None

Wraps the rendered rows in a custom container, e.g. for make_sortable.

render_detail instance-attribute

render_detail: DetailRenderer | None

Custom renderer for the detail view, replacing the default autosaving form.

include instance-attribute

include: list[str] | str

Fields to show; forwarded to ModelList when render_list_item is not set.

exclude instance-attribute

exclude: list[str] | str

Fields to hide; forwarded to ModelList when render_list_item is not set.

field_infos instance-attribute

field_infos: dict[str, FieldInfo]

Per-field FieldInfo overrides; forwarded to ModelList when render_list_item is not set.

profile instance-attribute

profile: str | None

Named field layout profile from Meta.profiles; forwarded when render_list_item is not set. Defaults to Meta.default_profile when omitted.

Field

The arguments of niceview.Field(), which builds a FieldInfo.

_FieldInfoInputs

Keyword options for FieldInfo(); mirrors its attributes for kwarg type-checking.

Source code in niceview/fieldinfo.py

class _FieldInfoInputs(typing_extensions.TypedDict, total=False):
    """Keyword options for FieldInfo(); mirrors its attributes for kwarg type-checking."""
    label: str
    """The field's label text."""
    placeholder: str
    """Placeholder text shown in an empty text-like widget."""

    field_type: type
    """Python type of the value. ModelForm sets this from the model annotation; set it
    explicitly for render_field()."""

    required: bool
    """Whether the field must have a value."""
    hidden: bool
    """Hide the field entirely."""
    editable: bool
    """Whether the widget accepts input; False renders it disabled."""
    hint: str
    """Help text below the widget (Quasar's `hint` prop); ignored by widgets with no hint slot."""
    description: str
    """Help text from pydantic's `description`; shown as hint or tooltip per `description_as=`,
    unless an explicit `hint`/`tooltip` wins."""
    widget_type: WidgetType
    """Which element renders the field; inferred from the type if omitted."""

    props: str
    """Quasar props string, merged on top of niceview's own."""
    classes: str
    """CSS classes for the widget."""
    style: str
    """Inline CSS style for the widget."""
    tooltip: str
    """Text shown on hover."""

    # choices for select/radio/toggle/checkbox_group widgets
    options: OptionsSource
    """Choices for select/radio/toggle/checkbox_group widgets."""

    # additional options when field is rendered in a ui.input widget
    password: bool
    """Mask the input (ui.input only)."""
    password_toggle_button: bool
    """Show/hide toggle for a password input."""
    autocomplete: list[str]
    """Autocomplete suggestions for a text input."""
    validation: ValidationFunction | ValidationDict
    """Extra validation beyond `required`: a NiceGUI ValidationFunction or dict."""

    # additional options when field is rendered as ui.number
    min: float
    """Minimum value (ui.number)."""
    max: float
    """Maximum value (ui.number)."""
    precision: int
    """Decimal places (ui.number)."""
    step: float
    """Increment step (ui.number)."""
    prefix: str
    """Text shown before the value (ui.number)."""
    suffix: str
    """Text shown after the value (ui.number)."""
    number_format: str
    """Display format of ui.number, e.g. '%.2f'. Named number_format, not format, to keep it
    apart from JSON Schema's `format`, which corresponds to widget_type."""

    # a clear button, on the select-like widgets and on every text input
    clearable: bool
    """Offer a clear button on select-like and text widgets. Clearing writes None."""

    # additional options when field is rendered as ui.select
    with_input: bool
    """Allow free-text filtering in ui.select."""
    multiple: bool
    """Allow selecting multiple values in ui.select."""
    key_generator: Callable[[Any], Any]
    """Generates a dict key for a new value typed into ui.select."""
    # validation same as in ui.input

    # additional options when field is rendered as ui.color_input
    color_preview: bool
    """Show a color swatch preview next to ui.color_input."""

    # additional options when the field is rendered as ui.input_chips
    new_value_mode: Literal['add', 'add-unique', 'toggle']
    """How ui.input_chips treats a typed value not already in the list."""

    # item type for list fields (editgrid) and relationship fields (modelselect)
    item_type: type
    """Item's pydantic type for editgrid/modelselect fields."""

    # options when field is used in a table or grid column
    table_label: str
    """Column header label; defaults to the field's label."""
    table_hidden: bool
    """Hide the column in a table/grid (the field may still show in a form)."""
    table_align: Literal['left', 'center', 'right']
    """Horizontal text alignment of the cell."""
    table_cell_style: str
    """Extra CSS for the cell, merged with table_align."""
    table_sortable: bool
    """Whether the column can be sorted."""
    table_sort: Literal['asc', 'desc']
    """Default sort order for the column."""
    table_filterable: bool
    """Show a filter row for the column; filter type inferred from the field type."""
    table_floating_filter: bool
    """Show a floating filter row for the column."""
    aggrid_type: str
    """ag-grid column type, e.g. 'numericColumn', 'rightAligned'."""
    aggrid: dict
    """Additional ag-grid column properties, merged on top of the computed ones."""

label instance-attribute

label: str

The field's label text.

placeholder instance-attribute

placeholder: str

Placeholder text shown in an empty text-like widget.

field_type instance-attribute

field_type: type

Python type of the value. ModelForm sets this from the model annotation; set it explicitly for render_field().

required instance-attribute

required: bool

Whether the field must have a value.

hidden instance-attribute

hidden: bool

Hide the field entirely.

editable instance-attribute

editable: bool

Whether the widget accepts input; False renders it disabled.

hint instance-attribute

hint: str

Help text below the widget (Quasar's hint prop); ignored by widgets with no hint slot.

description instance-attribute

description: str

Help text from pydantic's description; shown as hint or tooltip per description_as=, unless an explicit hint/tooltip wins.

widget_type instance-attribute

widget_type: WidgetType

Which element renders the field; inferred from the type if omitted.

props instance-attribute

props: str

Quasar props string, merged on top of niceview's own.

classes instance-attribute

classes: str

CSS classes for the widget.

style instance-attribute

style: str

Inline CSS style for the widget.

tooltip instance-attribute

tooltip: str

Text shown on hover.

options instance-attribute

options: OptionsSource

Choices for select/radio/toggle/checkbox_group widgets.

password instance-attribute

password: bool

Mask the input (ui.input only).

password_toggle_button instance-attribute

password_toggle_button: bool

Show/hide toggle for a password input.

autocomplete instance-attribute

autocomplete: list[str]

Autocomplete suggestions for a text input.

validation instance-attribute

validation: ValidationFunction | ValidationDict

Extra validation beyond required: a NiceGUI ValidationFunction or dict.

min instance-attribute

min: float

Minimum value (ui.number).

max instance-attribute

max: float

Maximum value (ui.number).

precision instance-attribute

precision: int

Decimal places (ui.number).

step instance-attribute

step: float

Increment step (ui.number).

prefix instance-attribute

prefix: str

Text shown before the value (ui.number).

suffix instance-attribute

suffix: str

Text shown after the value (ui.number).

number_format instance-attribute

number_format: str

Display format of ui.number, e.g. '%.2f'. Named number_format, not format, to keep it apart from JSON Schema's format, which corresponds to widget_type.

clearable instance-attribute

clearable: bool

Offer a clear button on select-like and text widgets. Clearing writes None.

with_input instance-attribute

with_input: bool

Allow free-text filtering in ui.select.

multiple instance-attribute

multiple: bool

Allow selecting multiple values in ui.select.

key_generator instance-attribute

key_generator: Callable[[Any], Any]

Generates a dict key for a new value typed into ui.select.

color_preview instance-attribute

color_preview: bool

Show a color swatch preview next to ui.color_input.

new_value_mode instance-attribute

new_value_mode: Literal['add', 'add-unique', 'toggle']

How ui.input_chips treats a typed value not already in the list.

item_type instance-attribute

item_type: type

Item's pydantic type for editgrid/modelselect fields.

table_label instance-attribute

table_label: str

Column header label; defaults to the field's label.

table_hidden instance-attribute

table_hidden: bool

Hide the column in a table/grid (the field may still show in a form).

table_align instance-attribute

table_align: Literal['left', 'center', 'right']

Horizontal text alignment of the cell.

table_cell_style instance-attribute

table_cell_style: str

Extra CSS for the cell, merged with table_align.

table_sortable instance-attribute

table_sortable: bool

Whether the column can be sorted.

table_sort instance-attribute

table_sort: Literal['asc', 'desc']

Default sort order for the column.

table_filterable instance-attribute

table_filterable: bool

Show a filter row for the column; filter type inferred from the field type.

table_floating_filter instance-attribute

table_floating_filter: bool

Show a floating filter row for the column.

aggrid_type instance-attribute

aggrid_type: str

ag-grid column type, e.g. 'numericColumn', 'rightAligned'.

aggrid instance-attribute

aggrid: dict

Additional ag-grid column properties, merged on top of the computed ones.