TinyBase logoTinyBase

useSetCellCallback

The useSetCellCallback hook returns a parameterized callback that can be used to set the value of a single Cell in a Store.

useSetCellCallback<Parameter>(
  tableId: string | GetId<Parameter>,
  rowId: string | GetId<Parameter>,
  cellId: string | GetId<Parameter>,
  getCell: (parameter: Parameter, store: Store) => Cell | MapCell,
  getCellDeps?: DependencyList,
  storeOrStoreId?: StoreOrStoreId,
  then?: (store: Store, cell: Cell | MapCell) => void,
  thenDeps?: DependencyList,
): ParameterizedCallback<Parameter>
TypeDescription
tableIdstring | GetId<Parameter>

The Id of the Table in the Store, or a GetId function that will return it.

rowIdstring | GetId<Parameter>

The Id of the Row in the Table, or a GetId function that will return it.

cellIdstring | GetId<Parameter>

The Id of the Cell in the Row to set, or a GetId function that will return it.

getCell(parameter: Parameter, store: Store) => Cell | MapCell

A function which returns the Cell value that will be used to update the Store, or a MapCell function to update it, based on the parameter the callback will receive (and which is most likely a DOM event).

getCellDeps?DependencyList

An optional array of dependencies for the getCell function, which, if any change, result in the regeneration of the callback. This parameter defaults to an empty array. Also use this to indicate the dependencies of any GetId functions if used as the tableId, rowId, or cellId arguments.

storeOrStoreId?StoreOrStoreId

The Store to be updated: omit for the default context Store, provide an Id for a named context Store, or provide an explicit reference.

then?(store: Store, cell: Cell | MapCell) => void

A function which is called after the mutation, with a reference to the Store and the Cell value (or MapCell function) used in the update.

thenDeps?DependencyList

An optional array of dependencies for the then function, which, if any change, result in the regeneration of the callback. This parameter defaults to an empty array.

returnsParameterizedCallback<Parameter>

A parameterized callback for subsequent use.

This hook is useful, for example, when creating an event handler that will mutate the data in the Store. In this case, the parameter will likely be the event, so that you can use data from it as part of the mutation.

The fourth parameter is a function which will produce the Cell object that will then be used to update the Store in the callback.

If that function has any other dependencies, the changing of which should also cause the callback to be recreated, you can provide them in an array in the optional fourth parameter, just as you would for any React hook with dependencies.

For convenience, you can optionally provide a then function (with its own set of dependencies) which will be called just after the Store has been updated. This is a useful place to call the addCheckpoint method, for example, if you wish to add the mutation to your application's undo stack.

The Store to which the callback will make the mutation (indicated by the hook's storeOrStoreId parameter) is always automatically used as a hook dependency for the callback.

Examples

This example uses the useSetCellCallback hook to create an event handler which updates the Store with a Cell value when the span element is clicked.

import {useRow, useSetCellCallback} from 'tinybase/ui-react';
import React from 'react';
import {createRoot} from 'react-dom/client';
import {createStore} from 'tinybase';

const store = createStore().setCell('pets', 'nemo', 'species', 'fish');
const App = () => {
  const handleClick = useSetCellCallback(
    'pets',
    'nemo',
    'bubbles',
    (e) => e.bubbles,
    [],
    store,
    (store, cell) => console.log(`Updated: ${cell}`),
  );
  return (
    <span id="span" onClick={handleClick}>
      {JSON.stringify(useRow('pets', 'nemo', store))}
    </span>
  );
};

const app = document.createElement('div');
createRoot(app).render(<App />);
const span = app.querySelector('span');
console.log(span.innerHTML);
// -> '{"species":"fish"}'

// User clicks the <span> element:
// -> span MouseEvent('click', {bubbles: true})
// -> 'Updated: true'

console.log(span.innerHTML);
// -> '{"species":"fish","bubbles":true}'

This example uses the useSetCellCallback hook to create an event handler which updates the Store via a MapCell function when the span element is clicked.

import {useRow, useSetCellCallback} from 'tinybase/ui-react';
import React from 'react';
import {createRoot} from 'react-dom/client';
import {createStore} from 'tinybase';

const store = createStore().setCell('pets', 'nemo', 'visits', 1);
const App = () => {
  const handleClick = useSetCellCallback(
    'pets',
    'nemo',
    'visits',
    (e) => (visits) => visits + (e.bubbles ? 1 : 0),
    [],
    store,
    () => console.log(`Updated with MapCell function`),
  );
  return (
    <span id="span" onClick={handleClick}>
      {JSON.stringify(useRow('pets', 'nemo', store))}
    </span>
  );
};

const app = document.createElement('div');
createRoot(app).render(<App />);
const span = app.querySelector('span');
console.log(span.innerHTML);
// -> '{"visits":1}'

// User clicks the <span> element:
// -> span MouseEvent('click', {bubbles: true})
// -> 'Updated with MapCell function'

console.log(span.innerHTML);
// -> '{"visits":2}'

Since

v1.0.0