diff --git a/docs/include_package-core.rst b/docs/include_package-core.rst
index 82e4fef1109..b46caba9c66 100644
--- a/docs/include_package-core.rst
+++ b/docs/include_package-core.rst
@@ -99,6 +99,75 @@ Example
     // on windows the path is: "\\\\.\\pipe\\geth.ipc"
     // on linux the path is: "/users/myuser/.ethereum/geth.ipc"
 
+-------------
+Configuration
+-------------
+
+.. code-block:: javascript
+
+    // ====
+    // Http
+    // ====
+
+    var Web3HttpProvider = require('web3-providers-http');
+
+    var options = {
+        keepAlive: true,
+        withCredentials: false,
+        timeout: 20000, // ms
+        headers: [
+            {
+                name: 'Access-Control-Allow-Origin',
+                value: '*'
+            },
+            {
+                ...
+            }
+        ],
+        agent: {
+            http: http.Agent(...),
+            baseUrl: ''
+        }
+    };
+
+    var provider = new Web3HttpProvider('http://localhost:8545', options);
+
+    // ==========
+    // Websockets
+    // ==========
+
+    var Web3WsProvider = require('web3-providers-ws');
+
+    var options = {
+        timeout: 30000, // ms
+
+        // Useful for credentialed urls, e.g: ws://username:password@localhost:8546
+        headers: {
+          authorization: 'Basic username:password'
+        },
+
+        // Useful if requests result are large
+        clientConfig: {
+          maxReceivedFrameSize: 100000000,   // bytes - default: 1MiB
+          maxReceivedMessageSize: 100000000, // bytes - default: 8MiB
+        },
+
+        // Enable auto reconnection
+        reconnect: {
+            auto: true,
+            delay: 5000, // ms
+            maxAttempts: 5,
+            onTimeout: false
+        }
+    };
+
+    var ws = new Web3WsProvider('ws://localhost:8546', options);
+
+
+More information for the Http and Websocket provider modules can be found here:
+
+    - `HttpProvider <https://github.com/ethereum/web3.js/tree/1.x/packages/web3-providers-http#usage>`_
+    - `WebsocketProvider <https://github.com/ethereum/web3.js/tree/1.x/packages/web3-providers-ws#usage>`_
 
 ------------------------------------------------------------------------------
 
diff --git a/packages/web3-providers-ws/README.md b/packages/web3-providers-ws/README.md
index 8569fa6dacf..28cc721fd29 100644
--- a/packages/web3-providers-ws/README.md
+++ b/packages/web3-providers-ws/README.md
@@ -2,7 +2,7 @@
 
 This is a sub package of [web3.js][repo]
 
-This is a websocket provider for [web3.js][repo].  
+This is a websocket provider for [web3.js][repo].
 Please read the [documentation][docs] for more.
 
 ## Installation
@@ -31,16 +31,33 @@ This will expose the `Web3WsProvider` object on the window object.
 var Web3WsProvider = require('web3-providers-ws');
 
 var options = {
-    timeout: 30000,
-    headers: { authorization: 'Basic username:password' },
+    timeout: 30000, // ms
+
+    // Useful for credentialed urls, e.g: ws://username:password@localhost:8546
+    headers: {
+      authorization: 'Basic username:password'
+    },
+
+    // Useful if requests are large
+    clientConfig: {
+      maxReceivedFrameSize: 100000000,   // bytes - default: 1MiB
+      maxReceivedMessageSize: 100000000, // bytes - default: 8MiB
+    },
+
+    // Enable auto reconnection
     reconnect: {
-        auto: false,
-        delay: 5000,
-        maxAttempts: false,
+        auto: true,
+        delay: 5000, // ms
+        maxAttempts: 5,
         onTimeout: false
     }
-}; // set a custom timeout at 30 seconds, credentials (you can also add the credentials to the URL: ws://username:password@localhost:8546), and enable WebSocket auto-reconnection
+};
+
 var ws = new Web3WsProvider('ws://localhost:8546', options);
+
+(Additional client config options can be found [here][1])
+
+[1]: https://github.com/web3-js/WebSocket-Node/blob/polyfill/globalThis/docs/WebSocketClient.md
 ```
 
 ## Types