From eb2adf17ef2491c0b2f6f7f39e3d31bb489e27f5 Mon Sep 17 00:00:00 2001
From: Sarah Dayan <sarah.dayan@algolia.com>
Date: Tue, 26 Jan 2021 14:04:57 +0100
Subject: [PATCH] docs: write "Basic configuration options" (#402)

---
 packages/website/docs/basic-options.md | 62 +++++++++++++++++++++-----
 1 file changed, 50 insertions(+), 12 deletions(-)

diff --git a/packages/website/docs/basic-options.md b/packages/website/docs/basic-options.md
index 95c7f513a..b4b198fcf 100644
--- a/packages/website/docs/basic-options.md
+++ b/packages/website/docs/basic-options.md
@@ -3,18 +3,56 @@ id: basic-options
 title: Basic configuration options
 ---
 
-:::note Draft
+Everything you need to create fantastic autocomplete experiences.
 
-This page needs to cover:
+We've built Autocomplete to give you unlimited flexibility while freeing you from having to think about things like keyboard navigation, accessibility, or UI state. **The library offers a wide variety of APIs to let you fully customize the behavior and rendering of your autocomplete.**
 
-- There are only two required params to create an autocomplete:
-  - You need to provide a selector for the **container** you want autocomplete to appear in.
-  - You need to define where to get the items to display using **getSources** (or a **plug-in** which provides **getSources**). Check our **Sources** core concept for more information.
-- Beyond this, there are many parameters you can use to customize the experience and help you with development. Here are some commonly used ones:
-  - Use **placeholder** to define the text that appears in the input when a user hasn’t typed anything.
-  - Use **autoFocus** to focus on the search box when the page is loaded and **openOnFocus** to display items as soon as a user selects the autocomplete (without typing anything).
-  - Use the **onStateChange** hook to call a function whenever the state changes (see our **State** core concept for more info).
-  - Use **`debug: true`** to keep the autocomplete panel with items open, even when the blur event occurs. (This is only meant to be used during development. See our **Debugging guide** for more info.)
-- Check out the **API reference** for a full list of params.
+Yet, only two parameters are required to create an autocomplete:
+- The **container** you want your autocomplete to go in.
+- The **sources** from which to get the items to display (see more in [**Sources**](sources)).
 
-:::
+```js title="JavaScript"
+import { autocomplete } from '@algolia/autocomplete-js';
+
+autocomplete({
+  container: '#autocomplete',
+  getSources() {
+    return [
+      {
+        getItems({ query }) {
+          return [
+            { label: 'Twitter', url: 'https://twitter.com' },
+            { label: 'GitHub', url: 'https://github.com' },
+          ].filter(({ label }) =>
+            label.toLowerCase().includes(query.toLowerCase())
+          );
+        },
+        getItemUrl({ item }) {
+          return item.url;
+        },
+        templates: {
+          item({ item }) {
+            return item.label;
+          },
+        },
+      },
+    ];
+  },
+});
+```
+
+The `container` options refers to where to inject the autocomplete in your HTML. It can be a [CSS selector](https://developer.mozilla.org/docs/Web/CSS/CSS_Selectors) or an [Element](https://developer.mozilla.org/docs/Web/API/HTMLElement). Make sure to provide a container (e.g., a `div`), not an `input`. Autocomplete generates a fully accessible search box for you.
+
+```html title="HTML"
+<div id="autocomplete"></div>
+```
+
+This is all you need to build a [fully functional, accessible, keyboard-navigable autocomplete](https://codesandbox.io/s/vigilant-dew-g2ezl).
+
+Now, this is a great start, but **you can go much further**. Here are some of the options you'll probably want to use next:
+- Use [`placeholder`](autocomplete-js#placeholder) to define the text that appears in the input before the user types anything.
+- Use [`autoFocus`](autocomplete-js#autofocus) to focus on the search box on page load, and [`openOnFocus`](autocomplete-js#openonfocus) to display items as soon as a user selects the autocomplete, even without typing.
+- Use the [`onStateChange`](autocomplete-js#onstatechange) lifecycle hook to execute code whenever the state changes.
+- Use [`debug: true`](autocomplete-js#debug) to keep the autocomplete panel open even when the blur event occurs (see [**Debugging**](debugging)).
+
+For a full list of all available parameters, check out the [API reference](autocomplete-js).