class edifice.components.forms.Form(data, config=None, label_map=None, defaults=None, on_submit=None, submit_text='Submit', layout=None)[source]

Bases: edifice._component.Component

A simple Form element to allow editting values stored in a StateManager.

For every key, value pair in the StateManager, a field is created in the Form, A field consists of a label (by default, the key, although this is configurable using label_map) and a form element, such as a TextInput or a Dropdown. The precise form element generated can be specified by the optional config prop. For entries whose form element is not specified in config, the following defaults are used, according to the type of value:

  • str: TextInput

  • int or float: TextInput. The input will the validated to be a number, and if the user enters a non number and unfocuses from the TextInput, an error message is printed.

  • bool: Checkbox

  • tuple (selection, options): A dropdown with the current selection and the list of options

  • Enum: dropdown

  • pathlib.Path: a file choice dialog

  • function: a label that displays the value of the function evaluated on the current form. The function

    is passed a dictionary containing all current values.

  • datetime.date: Three drop downs for year, month, and day.

  • datetime.time: NOT SUPPORTED YET Three dropdowns for hour, minute, second

  • datetime.datetime: NOT SUPPORTED YET Six dropdowns combining date and time

  • list: NOT SUPPORTED YET a list view. This is purely for display, and the user can’t modify this state.

  • np.array or pd.DataFrame: NOT SUPPORTED YET A table. This is purely for display, and the user can’t modify this state.

  • StateManager: **NOT SUPPORTED YET**a group box containing a sub-form. This sub-form cannot be submitted, except as part of the larger form’s submission process.

If the defaults dict is provided, a Reset button will appear, allowing the user to reset the form to default values.

If the on_submit callback is provided, a Submit button will appear. Clicking the button will trigger the callback, which is passed the StateManager.

The form is completely reactive, and all current values for form elements are accessible by the caller at any time (except when the input fails some type check guarantee, in which case the old value is maintained).


# Store a reference to the StateManager if you need to access it before submit
# You can also pass the StateManager used in other parts of your application if you wish
# for the form state and the other state to be connected.
    "First Name": "",
    "Last Name": "",
    "Date of Birth": datetime.date(1970, 1, 1),
    "Programming Experience": StateManager({
        "Years of Python Experience": 0,
        "How much do like Python?": ("Neutral", ["Hate it", "Neutral", "Love it"])
        "Years of JavaScript Experience": 0,
        "How much do like JavaScript?": ("Neutral", ["Hate it", "Neutral", "Love it"])
    on_submit=lambda state: do_something_with_data(state)
  • data (StateManager) – the data that the Form displays and modifies

  • config (Optional[Mapping[str, FormElement]]) – (optional) NOT SUPPORTED YET the form element to use in displaying each entry in data. You don’t have to provide configs for every key in data; sensible defaults will be used if the config is unspecified.

  • label_map (Optional[Mapping[str, str]]) – (optional) the label to use for each key. By default, the key itself is used. You don’t have to provide overrides for every key in data.

  • defaults (Optional[Mapping[str, Any]]) – (optional) the default value for each key. Providing this dictionary will cause a reset button to appear. You don’t have to provide defaults for every key in data; only the provided keys will be reset.

  • on_submit (Optional[Callable[[Mapping[str, Any]], None]]) – (optional) the callback once the user presses the submit button. If not provided, a submit button will not appear. The callback is passed a dictionary containing the current form values.

  • submit_text (str) – the text for the submit button.

  • layout (Optional[Any]) –

    a description of how the form is to be laid out. By default, each form element would appear in its own row. If layout is “row” or “column”, the elements will be laid out in a row or column. If layout is a 1-D list of keys in data, the layout will be a row:

    [“First Name”, “Last Name”, …]

    If layout is a 2-D list, each internal list will be a row, and the outer list will be a stack of rows:
    [[“First Name”, “Last Name”],

    [“Date of Birth”], [“Street Address”], [“City”, “State”, “Zipcode”]]



Logic for rendering, must be overridden.



The children of this component.


The props of this component.