From 7569e810e77eb7daa9a93128e454e50e77511e64 Mon Sep 17 00:00:00 2001 From: Jim Date: Tue, 10 Mar 2015 10:49:21 -0700 Subject: [PATCH] Added docs about the first-parameter-is-function version of setState. --- docs/docs/ref-02-component-api.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/docs/docs/ref-02-component-api.md b/docs/docs/ref-02-component-api.md index b2d3bf99dd..b0f2301735 100644 --- a/docs/docs/ref-02-component-api.md +++ b/docs/docs/ref-02-component-api.md @@ -14,10 +14,27 @@ Instances of a React Component are created internally in React when rendering. T ### setState ```javascript -setState(object nextState[, function callback]) +setState(function|object nextState[, function callback]) +``` +Merges nextState with the current state. This is the primary method you use to trigger UI updates from event handlers and server request callbacks. + +The first argument can be an object (containing zero or more keys to update) or a function (of state and props) that returns an object containing keys to update. + +Here is the simple object usage... + +```javascript +setState({mykey: 'my new value'}); ``` -Merges nextState with the current state. This is the primary method you use to trigger UI updates from event handlers and server request callbacks. In addition, you can supply an optional callback function that is executed once `setState` is completed and the component is re-rendered. +It's also possible to pass a function with the signature `function(state, props)`. This can be useful in some cases when you want to enqueue an atomic update that consults the previous value of state+props before setting any values. For instance, suppose we wanted to increment a value in state: + +```javascript +setState(function(previousState, currentProps) { + return {myInteger: previousState.myInteger + 1}; +});` +``` + +The second (optional) parameter is a callback function that will be executed once `setState` is completed and the component is re-rendered. > Notes: >