State in Blocks

We covered State in Interfaces, this guide takes a look at state in Blocks, which works mostly the same.

Global State

Global state in Blocks works the same as in Interface. Any variable created outside a function call is a reference shared between all users.

Session State

Gradio supports session state, where data persists across multiple submits within a page session, in Blocks apps as well. To reiterate, session data is not shared between different users of your model. To store data in a session state, you need to do three things:

1. Create a gr.State() object. If there is a default value to this stateful object, pass that into the constructor.
2. In the event listener, put the State object as an input and output.
3. In the event listener function, add the variable to the input parameters and the return value.

Let's take a look at a game of hangman.

import gradio as gr

secret_word = "gradio"

with gr.Blocks() as demo:    
    used_letters_var = gr.State([])
    with gr.Row() as row:
        with gr.Column():
            input_letter = gr.Textbox(label="Enter letter")
            btn = gr.Button("Guess Letter")
        with gr.Column():
            hangman = gr.Textbox(
                label="Hangman",
                value="_"*len(secret_word)
            )
            used_letters_box = gr.Textbox(label="Used Letters")

    def guess_letter(letter, used_letters):
        used_letters.append(letter)
        answer = "".join([
            (letter if letter in used_letters else "_")
            for letter in secret_word
        ])
        return {
            used_letters_var: used_letters,
            used_letters_box: ", ".join(used_letters),
            hangman: answer
        }
    btn.click(
        guess_letter, 
        [input_letter, used_letters_var],
        [used_letters_var, used_letters_box, hangman]
        )
demo.launch()

Let's see how we do each of the 3 steps listed above in this game:

1. We store the used letters in used_letters_var. In the constructor of State, we set the initial value of this to [], an empty list.
2. In btn.click(), we have a reference to used_letters_var in both the inputs and outputs.
3. In guess_letter, we pass the value of this State to used_letters, and then return an updated value of this State in the return statement.

With more complex apps, you will likely have many State variables storing session state in a single Blocks app.

Learn more about State in the docs.