Server Functions

When a Server Function is defined with the"use server" directive, your framework will automatically create a reference to the Server Function, and pass that reference to the Client Component. When that function is called on the client, React will send a request to the server to execute the function, and return the result.

Server Functions can be created in Server Components and passed as props to Client Components, or they can be imported and used in Client Components.

Usage

Creating a Server Function from a Server Component

Server Components can define Server Functions with the"use server" directive:

// Server Component
importButtonfrom'./Button';

functionEmptyNote(){
asyncfunctioncreateNoteAction(){
// Server Function
'use server';

awaitdb.notes.create();
}

return<ButtononClick={createNoteAction}/>;
}

When React renders theEmptyNote Server Component, it will create a reference to thecreateNoteAction function, and pass that reference to theButton Client Component. When the button is clicked, React will send a request to the server to execute thecreateNoteAction function with the reference provided:

"use client";

exportdefaultfunctionButton({onClick}){
console.log(onClick);
// {$$typeof: Symbol.for("react.server.reference"), $$id: 'createNoteAction'}
return<buttononClick={()=>onClick()}>Create Empty Note</button>
}

For more, see the docs for"use server".

Importing Server Functions from Client Components

Client Components can import Server Functions from files that use the"use server" directive:

"use server";

exportasyncfunctioncreateNote(){
awaitdb.notes.create();
}

When the bundler builds theEmptyNote Client Component, it will create a reference to thecreateNote function in the bundle. When thebutton is clicked, React will send a request to the server to execute thecreateNote function using the reference provided:

"use client";
import{createNote}from'./actions';

functionEmptyNote(){
console.log(createNote);
// {$$typeof: Symbol.for("react.server.reference"), $$id: 'createNote'}
<buttononClick={()=>createNote()}/>
}

For more, see the docs for"use server".

Server Functions with Actions

Server Functions can be called from Actions on the client:

"use server";

exportasyncfunctionupdateName(name){
if(!name){
return{error:'Name is required'};
}
awaitdb.users.updateName(name);
}

"use client";

import{updateName}from'./actions';

functionUpdateName(){
const[name,setName] =useState('');
const[error,setError] =useState(null);

const[isPending,startTransition] =useTransition();

constsubmitAction =async()=>{
startTransition(async()=>{
const{error} =awaitupdateName(name);
if(error){
setError(error);
}else{
setName('');
}
})
}

return(
<formaction={submitAction}>
<inputtype="text"name="name"disabled={isPending}/>
{error &&<span>Failed:{error}</span>}
</form>
)
}

This allows you to access theisPending state of the Server Function by wrapping it in an Action on the client.

For more, see the docs forCalling a Server Function outside of<form>

Server Functions with Form Actions

Server Functions work with the new Form features in React 19.

You can pass a Server Function to a Form to automatically submit the form to the server:

"use client";

import{updateName}from'./actions';

functionUpdateName(){
return(
<formaction={updateName}>
<inputtype="text"name="name"/>
</form>
)
}

When the Form submission succeeds, React will automatically reset the form. You can adduseActionState to access the pending state, last response, or to support progressive enhancement.

For more, see the docs forServer Functions in Forms.

Server Functions withuseActionState

You can call Server Functions withuseActionState for the common case where you just need access to the action pending state and last returned response:

"use client";

import{updateName}from'./actions';

functionUpdateName(){
const[state,submitAction,isPending] =useActionState(updateName,{error:null});

return(
<formaction={submitAction}>
<inputtype="text"name="name"disabled={isPending}/>
{state.error &&<span>Failed:{state.error}</span>}
</form>
);
}

When usinguseActionState with Server Functions, React will also automatically replay form submissions entered before hydration finishes. This means users can interact with your app even before the app has hydrated.

For more, see the docs foruseActionState.

Progressive enhancement withuseActionState

Server Functions also support progressive enhancement with the third argument ofuseActionState.

"use client";

import{updateName}from'./actions';

functionUpdateName(){
const[,submitAction] =useActionState(updateName,null,`/name/update`);

return(
<formaction={submitAction}>
      ...
</form>
);
}

When thepermalink is provided touseActionState, React will redirect to the provided URL if the form is submitted before the JavaScript bundle loads.

For more, see the docs foruseActionState.