Hooks
Hooks let you use state and other deephaven.ui features in your components. Hooks are functions that let you “hook into” state and lifecycle features from function components, encapsulating code and logic to avoid duplication. You can either use the built-in hooks or combine them to build your own.
Example
from deephaven import ui
@ui.component
def ui_counter():
count, set_count = ui.use_state(0)
return ui.button(f"Pressed {count} times", on_press=lambda: set_count(count + 1))
counter = ui_counter()
UI recommendations
- Hooks must be used within components or other hooks: Hooks require a rendering context, and therefore can only be used within component functions or other hooks. They cannot be used in regular Python functions or outside of components.
- All hooks start with
use_
: For example,use_state
is a hook that lets you add state to your components. - Hooks must be called at the top level: Do not use hooks inside loops, conditions, or nested functions. This ensures that hooks are called in the same order each time a component renders. If you want to use one in a conditional or a loop, extract that logic to a new component and put it there.
Built-in hooks
Below are all the built-in hooks that deephaven.ui provides.
State hooks
State lets a component remember some data between renders and trigger a re-render when the data changes. For example, a counter component might use state to keep track of the current count.
The use_state
hook adds state to a component.
Ref hooks
A ref provides a way to hold a value that isn’t used for re-rendering. Unlike with state, updating a ref does not re-render your component.
use_ref
returns a mutable ref object whose.current
property is initialized to the passed argument.
Effect hooks
An effect hook lets you perform side effects in your components; for example, data fetching, setting up a subscription, and manually synchronizing with an external system.
use_effect
lets you perform side effects in your components.
Performance hooks
Performance hooks let you optimize components for performance. They allow you to memoize expensive computations so that you can avoid re-running them on every render, or skip unnecessary re-rendering.
use_memo
lets you memoize expensive computations.use_callback
lets you cache a function definition before passing to an effect or child component, preventing unnecessary rendering. It’s likeuse_memo
but specifically for functions.
Data hooks
Data hooks let you use data from within a Deephaven table in your component.
use_table_data
lets you use the full table contents as a dictionary of rows and columns.use_column_data
lets you use the data of one column as a list.use_row_data
lets you use the data of one row as a dictionary.use_row_list
lets you use the data of one row as a list.use_cell_data
lets you use the data of one cell.use_table_listener
lets you listen to a table for updates.
Create custom hooks
You can create your own hooks to reuse stateful logic between components. A custom hook is a JavaScript function whose name starts with use
and that may call other hooks. For example, let’s say you want to create a custom hook that checks whether a table cell is odd. You can create a custom hook called use_is_cell_odd
:
from deephaven import time_table, ui
def use_is_cell_odd(table):
cell_value = ui.use_cell_data(table, 0)
return cell_value % 2 == 1
@ui.component
def ui_table_odd_cell(table):
is_odd = use_is_cell_odd(table)
return ui.view(f"Is the cell odd? {is_odd}")
_table = time_table("PT1s").update("x=i").view("x").tail(1)
table_odd_cell = ui_table_odd_cell(_table)
Notice at the end of our custom hook, we check if the cell value is odd and return the result. We then use this custom hook in our component to display whether the cell is odd.