Form data in examples

[eddyizm]

I have been pouring over the docs as I build out a native app. I am noticing though that I don't see any example of a regular vanilla form, much less a complex one.

Searched the discord/reddit and these issues and came across this discussion. That would be good to have in the docs unless I have missed it in the extensive documentation in which case, please feel free to point me to them.

[falkoschindler]

Thanks for the feedback, @eddyizm! You're right that we don't have a dedicated "form" example in the docs. NiceGUI takes a different approach than traditional HTML forms — instead of a <form> element with a submit action, you compose individual input elements and collect their values directly in Python.

Here are the key patterns:

Simple form with direct value access:

from nicegui import ui

name = ui.input('Name')
email = ui.input('Email')

def submit():
    print(f'{name.value}, {email.value}')
    ui.notify('Submitted!')

ui.button('Submit', on_click=submit)

ui.run()

Using data binding (recommended for larger forms):

from nicegui import ui
from dataclasses import dataclass

@dataclass
class FormData:
    name: str = ''
    email: str = ''
    age: int = 0

data = FormData()

ui.input('Name').bind_value(data, 'name')
ui.input('Email').bind_value(data, 'email')
ui.number('Age').bind_value(data, 'age')

def submit():
    print(data)  # FormData(name='...', email='...', age=...)
    ui.notify('Submitted!')

ui.button('Submit', on_click=submit)

ui.run()

With validation:

from nicegui import ui

name = ui.input('Name', validation={'Required': lambda v: len(v) > 0})
email = ui.input('Email', validation={'Invalid email': lambda v: '@' in v})

def submit():
    if all(field.validate() for field in [name, email]):
        ui.notify('Valid!', type='positive')
    else:
        ui.notify('Please fix errors', type='negative')

ui.button('Submit', on_click=submit)

ui.run()

Some helpful doc pages:

• Input with validation
• Binding properties

That said, having a dedicated "form" example combining these patterns in one place is a good idea — we'll keep it in mind for the docs.

[eddyizm]

thanks for this straight forward sample. I am getting back to this and trying to use this framework for a POC to show my director it's benefits.

I was actually already going to the binding when you had pointed it out but what has thrown me for a loop is, I can set up a form and do what i need to do and then i can also upload a file with the nice/fancy upload widget (godsend really!)
However tying them together into one form has really wrecked my mind.

I've started to fall back to a stepper pattern to break it up but really, I would be prefer to handle them together in one form, eg expect a attachment when a form is uploaded.

Am i missing something obvious in the docs for this?

[falkoschindler]

Not missing anything obvious — this is just a pattern you need to build yourself, since ui.upload is event-driven rather than a passive form field.

The key idea: store the uploaded file(s) in a variable during on_upload, then read that variable when the submit button is clicked.

Here is a minimal example:

from dataclasses import dataclass
from nicegui import events, ui

@dataclass
class FormData:
    name: str = ''
    email: str = ''
    file_content: bytes | None = None
    file_name: str | None = None

data = FormData()

ui.input('Name').bind_value(data, 'name')
ui.input('Email').bind_value(data, 'email')

async def on_upload(e: events.UploadEventArguments):
    data.file_content = await e.file.read()
    data.file_name = e.file.name
    ui.notify(f'File ready: {e.file.name}')

ui.upload(label='Attachment', on_upload=on_upload, auto_upload=True)

def submit():
    if not data.name or not data.email:
        ui.notify('Please fill in all fields', type='negative')
        return
    if data.file_content is None:
        ui.notify('Please attach a file', type='negative')
        return
    # All data is now available together:
    print(f'{data.name}, {data.email}, file: {data.file_name} ({len(data.file_content)} bytes)')
    ui.notify('Submitted!', type='positive')

ui.button('Submit', on_click=submit)

ui.run()

Hope that unblocks you!

[eddyizm]

This is really great! I had gotten closer to this since my message and the one trick that I needed and was not aware of was using
auto_upload=True is the key. I did not yet add the async part but that will probably be the last piece I needed.

If you like, I can open a PR and add this to the docs?

Thank you!

[falkoschindler]

Yes, a PR would be welcome! The best place might be a new "Form" demo at the end of the Binding Properties documentation section (after "Bindable dataclass"), since forms in NiceGUI are essentially a binding pattern — bind inputs to a data model, validate, and submit.