diff --git a/packages/replace/README.md b/packages/replace/README.md
index abb42e5f7..4b415d911 100644
--- a/packages/replace/README.md
+++ b/packages/replace/README.md
@@ -114,6 +114,31 @@ Default: `null`
 
 A [minimatch pattern](https://github.com/isaacs/minimatch), or array of patterns, which specifies the files in the build the plugin should operate on. By default all files are targeted.
 
+### `values`
+
+Type: `{ [key: String]: Replacement }`, where `Replacement` is either a string or a `function` that returns a string.
+Default: `{}`
+
+To avoid mixing replacement strings with the other options, you can specify replacements in the `values` option. For example, the following signature:
+
+```js
+replace({
+  include: ["src/**/*.js"],
+  changed: "replaced"
+});
+```
+
+Can be replaced with:
+
+```js
+replace({
+  include: ["src/**/*.js"],
+  values: {
+    changed: "replaced"
+  }
+});
+```
+
 ## Word Boundaries
 
 By default, values will only match if they are surrounded by _word boundaries_.