Skip to content
LogoLogo

Add Picked to your application

In this tutorial we make a color survey and put it on a page. We build the flow in the Picked dashboard, connect the SDK to it, and see the survey in a browser.

At the end you have one experience, one step, one field, and a page that shows them.

Before you start

  • A Picked account, and an organization in it.
  • Node 20 or later.
  • A web application that runs React or Svelte. A new Vite application is enough.

1. Make a project

A project is one site or one application.

  1. Sign in to the dashboard.
  2. Open your organization.
  3. Click New Project.
  4. Enter the name Tutorial.
  5. Click Create.

The project home page opens. It shows a project ID near the top. Copy that ID. Every step after this one needs it.

2. Make a field

A field collects one answer from your visitor.

  1. Click Fields in the sidebar.
  2. Click New field.
  3. Enter the name Color. The dashboard fills in the label and the key for you.
  4. Change the label to Which color do you like most?.
  5. Leave the key as color.
  6. Choose the type Text.
  7. Click Create field.
The fields list for a workspace on the Picked dashboard

The field now appears in the fields list.

3. Make the experience

  1. Click Flows in the sidebar. The experiences list opens.
  2. Click New experience.
  3. Enter the name Color survey.
  4. Leave Type on the Flow option.
  5. Open Advanced.
  6. Enter the component name ColorSurvey.
  7. Click Create flow.

The flow builder opens with an empty canvas. One gray circle is on the left. That circle is the origin, and every flow starts there.

4. Make a step

A step is one screen that your visitor sees. It holds your field. You make one from the library, on the left of the flow builder.

  1. Find the Steps section in the library.
  2. Click the + next to it.
  3. Enter the name Question. The key fills in as question.
  4. Click Create step.

The flow builder opens again, and your step is in the library.

5. Build the flow

  1. Find your Question step in the library on the left.
  2. Drag it onto the canvas.
  3. Drag from the output handle of the origin to the input handle of your step. An arrow joins them.
  4. Drag your Color field from the library onto the step node.
  5. Click Save in the toolbar.

The subtitle of the step node now reads one field. Your flow is one step long, and it starts at the origin.

6. Publish the workspace

Your visitors see nothing until you publish.

  1. Click Publish in the workspace toolbar.
  2. Read the change preview.
  3. Click Publish to confirm.

7. Connect the SDK

Install the client and the adapter for your framework.

npm install picked @picked/react

Now write the component that renders the step. Put it in ColorSurvey.tsx, or in ColorSurvey.svelte. It reads the fields of the active step and puts each one in a form.

import { useStep, useStoreGlobal } from '@picked/react/hooks'
 
export function ColorSurvey() {
  const { fields, form } = useStep()
  const currentFields = useStoreGlobal(fields)
 
  return (
    <form {...form.props}>
      {currentFields.map((field) => (
        <div key={field.id}>
          <label htmlFor={field.id}>{field.label}</label>
          <input
            id={field.id}
            name={field.id}
            value={field.value ?? ''}
            onChange={field.onChange}
            onBlur={field.onBlur}
          />
        </div>
      ))}
      <button type="submit">Continue</button>
    </form>
  )
}

Then start the client from picked.ts. Put your project ID in projectId. The key in components must match the component name that you entered in step 4.

import { createClient } from 'picked'
import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
import { adaptReactComponent } from '@picked/react'
import { reactFrameworkPlugin } from '@picked/react/plugins/framework'
import { ColorSurvey } from './ColorSurvey'
 
export const picked = createClient({
  projectId: 'your-project-id',
  components: {
    ColorSurvey: adaptReactComponent(ColorSurvey),
  },
  plugins: [reactFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
})
 
picked.start()

dynamicExperiencesPlugin reads the published configuration of your project. It registers your experience, your step, and your field. You declare none of them in code.

8. See it

Start your application and open it in a browser.

Your survey appears. It shows the label Which color do you like most? and one text input. Both come from the dashboard, and neither is in your code.

9. Change it without a deployment

This step shows you what the dashboard controls.

  1. Go back to the dashboard.
  2. Open your Color field.
  3. Change the label to Which color do you like least?.
  4. Click Save.
  5. Publish the workspace again.
  6. Open the page in your browser again.

The question changes. You edited no code and you deployed nothing.

What you built

You have an experience that you control from the dashboard and render in your own application. The dashboard holds the flow, the step, and the field. Your code holds only the component and the client.

To change the label, the field type, or the order of the steps, edit the workspace and publish again. You deploy no code.

Where to go next