diff --git a/DEVELOPER.md b/DEVELOPER.md
index 83139cd..4fd2064 100644
--- a/DEVELOPER.md
+++ b/DEVELOPER.md
@@ -1,23 +1,11 @@
## Developer Notes
-This was a very old script which I revamped in Dec 2024 to bring it into the 21st century. Version `4.0.0` now uses Typescript,
-modern rollup + babel and jest for testing, plus uses this crazy new thing called "hooks" in React.
+This was a very old script which I revamped in Dec 2024 to bring it into the 21st century. Version `4.0.0` now uses Turborepo, Typescript,
+modern rollup + babel, jest for testing, modern React, Docusaurus for the doc, eslint and prettier.
-The dev environment is functional but needs work.
-
-`yarn build` -> builds the script.
-`yarn` - bootstraps the app. Also builds it.
-`yarn test` - runs the tests. Note, if you're altering the code run `yarn && yarn test` (see "Ugly bits" below).
-
-Ugly bits:
-
-- The country-regions data set is very large, so to keep bundle sizes down, the rollup build for this script parses
- the data and minifies it as much as it can. That's done in via a custom rollup plugin. It works fine, but makes local dev a
- bit awkward, e.g. running the tests while tweaking the code. For that you have to run `yarn && yarn test` to first rebuild,
- then run the tests - and the tests are ran on the `/dist` result. Awkward. This'd be nice to rethink.
-- The `/example` folder is a mess. It's very data, requires a bit of custom setup to bootstrap both the main repo and that. Plus,
- just like the tests it won't auto-reload when you change the source: you have to do a rebuild and even restart the server.
-- needs linting + prettier set up.
+`pnpm install` - bootstraps the monorepo
+`npm run dev` - starts dev mode.
+`npm run test` - runs the tests
### Notes for next 4.x release
diff --git a/apps/docs/docs/Demos/BasicUsage.mdx b/apps/docs/docs/Demos/BasicUsage.mdx
index fb509f0..2758962 100644
--- a/apps/docs/docs/Demos/BasicUsage.mdx
+++ b/apps/docs/docs/Demos/BasicUsage.mdx
@@ -3,7 +3,7 @@ title: Basic Usage
sidebar_position: 1
---
-import BasicUsage from '@site/src/components/examples/BasicUsage';
+import BasicUsage from '@site/src/components/demos/BasicUsage';
Let's get started! This first demo shows the basic usage of the script, using minimal settings. As you can see, you're
responsible for tracking state, but the tools handles rendering the appropriate countries and regions.
diff --git a/apps/docs/docs/Demos/features/CountryBlacklist.mdx b/apps/docs/docs/Demos/features/CountryBlacklist.mdx
new file mode 100644
index 0000000..c65d4ed
--- /dev/null
+++ b/apps/docs/docs/Demos/features/CountryBlacklist.mdx
@@ -0,0 +1,59 @@
+---
+title: Country Blacklist
+sidebar_position: 9
+---
+
+import CountryBlacklist from '@site/src/components/demos/features/CountryBlacklist';
+
+The `blacklist` prop omits those countries from the dropdown. This demo hides all countries starting with `A`.
+The values are found in the `countryShortCode` value in the [source data package](https://github.com/country-regions/country-region-data/blob/master/data.json).
+
+
+
+---
+
+```tsx
+import React, { useState } from 'react';
+import { CountryDropdown, RegionDropdown } from 'react-country-region-selector';
+
+const CountryBlacklist = () => {
+ const [country, setCountry] = useState('');
+ const [region, setRegion] = useState('');
+
+ return (
+ <>
+ setCountry(val)}
+ // highlight-start
+ blacklist={[
+ 'AF',
+ 'AX',
+ 'AL',
+ 'DZ',
+ 'AS',
+ 'AD',
+ 'AO',
+ 'AI',
+ 'AQ',
+ 'AG',
+ 'AR',
+ 'AM',
+ 'AW',
+ 'AU',
+ 'AT',
+ 'AZ',
+ ]}
+ // highlight-end
+ />
+ setRegion(val)}
+ />
+ >
+ );
+};
+
+export default CountryBlacklist;
+```
diff --git a/apps/docs/docs/Demos/CountryWhitelist.mdx b/apps/docs/docs/Demos/features/CountryWhitelist.mdx
similarity index 92%
rename from apps/docs/docs/Demos/CountryWhitelist.mdx
rename to apps/docs/docs/Demos/features/CountryWhitelist.mdx
index b44a7b0..82c3446 100644
--- a/apps/docs/docs/Demos/CountryWhitelist.mdx
+++ b/apps/docs/docs/Demos/features/CountryWhitelist.mdx
@@ -3,7 +3,7 @@ title: Country Whitelist
sidebar_position: 8
---
-import CountryWhitelist from '@site/src/components/examples/CountryWhitelist';
+import CountryWhitelist from '@site/src/components/demos/features/CountryWhitelist';
The `whitelist` prop on the CountryDropdown component limits the listed countries to those that you specify. The
values are found in the `countryShortCode` value in the [source data package](https://github.com/country-regions/country-region-data/blob/master/data.json).
diff --git a/apps/docs/docs/Demos/CustomDefaultOptionLabels.mdx b/apps/docs/docs/Demos/features/CustomDefaultOptionLabels.mdx
similarity index 92%
rename from apps/docs/docs/Demos/CustomDefaultOptionLabels.mdx
rename to apps/docs/docs/Demos/features/CustomDefaultOptionLabels.mdx
index b228aa4..3fb1b93 100644
--- a/apps/docs/docs/Demos/CustomDefaultOptionLabels.mdx
+++ b/apps/docs/docs/Demos/features/CustomDefaultOptionLabels.mdx
@@ -3,7 +3,7 @@ title: Custom Default Option Labels
sidebar_position: 4
---
-import CustomDefaultOptionLabels from '@site/src/components/examples/CustomDefaultOptionLabels';
+import CustomDefaultOptionLabels from '@site/src/components/demos/features/CustomDefaultOptionLabels';
In case you want to localize the strings or just change the defaults, take a look at the following props:
diff --git a/apps/docs/docs/Demos/DisableEmptyRegionField.mdx b/apps/docs/docs/Demos/features/DisableEmptyRegionField.mdx
similarity index 89%
rename from apps/docs/docs/Demos/DisableEmptyRegionField.mdx
rename to apps/docs/docs/Demos/features/DisableEmptyRegionField.mdx
index 630a50a..0d14965 100644
--- a/apps/docs/docs/Demos/DisableEmptyRegionField.mdx
+++ b/apps/docs/docs/Demos/features/DisableEmptyRegionField.mdx
@@ -3,7 +3,7 @@ title: Disable Empty Region Field
sidebar_position: 3
---
-import DisableEmptyRegionField from '@site/src/components/examples/DisableEmptyRegionField';
+import DisableEmptyRegionField from '@site/src/components/demos/features/DisableEmptyRegionField';
When the user hasn't selected a country, nothing's going to show up in the Region dropdown. If you want to disable it,
use the `disableWhenEmpty` prop.
diff --git a/apps/docs/docs/Demos/features/DisableFields.mdx b/apps/docs/docs/Demos/features/DisableFields.mdx
new file mode 100644
index 0000000..e595e20
--- /dev/null
+++ b/apps/docs/docs/Demos/features/DisableFields.mdx
@@ -0,0 +1,42 @@
+---
+title: Disable Fields
+sidebar_position: 12
+---
+
+import DisableFields from '@site/src/components/demos/features/DisableFields';
+
+The `disabled` prop can be used on either component.
+
+
+
+---
+
+```tsx
+import React, { useState } from 'react';
+import { CountryDropdown, RegionDropdown } from 'react-country-region-selector';
+
+const DisableFields = () => {
+ const [country, setCountry] = useState('');
+ const [region, setRegion] = useState('');
+
+ return (
+ <>
+ setCountry(val)}
+ // highlight-next-line
+ disabled={true}
+ />
+ setRegion(val)}
+ // highlight-next-line
+ disabled={true}
+ />
+ >
+ );
+};
+
+export default DisableFields;
+```
diff --git a/apps/docs/docs/Demos/NameIdClassAttrs.mdx b/apps/docs/docs/Demos/features/NameIdClassAttrs.mdx
similarity index 93%
rename from apps/docs/docs/Demos/NameIdClassAttrs.mdx
rename to apps/docs/docs/Demos/features/NameIdClassAttrs.mdx
index aa7004c..b24c0ab 100644
--- a/apps/docs/docs/Demos/NameIdClassAttrs.mdx
+++ b/apps/docs/docs/Demos/features/NameIdClassAttrs.mdx
@@ -3,7 +3,7 @@ title: Name, ID, Class attributes
sidebar_position: 5
---
-import NameIdClassAttrs from '@site/src/components/examples/NameIdClassAttrs';
+import NameIdClassAttrs from '@site/src/components/demos/features/NameIdClassAttrs';
This demo shows how to set `name`, `id` and `class` attributes on each component.
diff --git a/apps/docs/docs/Demos/NoDefaultOption.mdx b/apps/docs/docs/Demos/features/NoDefaultOption.mdx
similarity index 92%
rename from apps/docs/docs/Demos/NoDefaultOption.mdx
rename to apps/docs/docs/Demos/features/NoDefaultOption.mdx
index c7a38ad..650e97e 100644
--- a/apps/docs/docs/Demos/NoDefaultOption.mdx
+++ b/apps/docs/docs/Demos/features/NoDefaultOption.mdx
@@ -3,7 +3,7 @@ title: No Default Option
sidebar_position: 2
---
-import NoDefaultOption from '@site/src/components/examples/NoDefaultOption';
+import NoDefaultOption from '@site/src/components/demos/features/NoDefaultOption';
The `showDefaultOption` boolean prop (default: `true`) can be set on both `CountryDropdown` and `RegionDropdown`. When set to
`false` the default "Select Country" / "Select Region" option won't appear.
diff --git a/apps/docs/docs/Demos/features/RegionBlacklist.mdx b/apps/docs/docs/Demos/features/RegionBlacklist.mdx
new file mode 100644
index 0000000..7c3cdd2
--- /dev/null
+++ b/apps/docs/docs/Demos/features/RegionBlacklist.mdx
@@ -0,0 +1,47 @@
+---
+title: Region Blacklist
+sidebar_position: 11
+---
+
+import RegionBlacklist from '@site/src/components/demos/features/RegionBlacklist';
+
+The `blacklist` prop on the RegionDropdown copmonent lets you hide specific regions from the list. This hides
+Alberta and BC from Canada's regions and Washington and Texas from US. The
+values are found in the `countryShortCode` value in the [source data package](https://github.com/country-regions/country-region-data/blob/master/data.json).
+
+
+
+---
+
+```tsx
+import React, { useState } from 'react';
+import { CountryDropdown, RegionDropdown } from 'react-country-region-selector';
+
+const RegionBlacklist = () => {
+ const [country, setCountry] = useState('');
+ const [region, setRegion] = useState('');
+
+ return (
+ <>
+ setCountry(val)}
+ whitelist={['CA', 'US']}
+ />
+ setRegion(val)}
+ // highlight-start
+ blacklist={{
+ CA: ['AB', 'BC'],
+ US: ['WA', 'TX'],
+ }}
+ // highlight-end
+ />
+ >
+ );
+};
+
+export default RegionBlacklist;
+```
diff --git a/apps/docs/docs/Demos/features/RegionWhitelist.mdx b/apps/docs/docs/Demos/features/RegionWhitelist.mdx
new file mode 100644
index 0000000..2326d34
--- /dev/null
+++ b/apps/docs/docs/Demos/features/RegionWhitelist.mdx
@@ -0,0 +1,47 @@
+---
+title: Region Whitelist
+sidebar_position: 10
+---
+
+import RegionWhitelist from '@site/src/components/demos/features/RegionWhitelist';
+
+The `whitelist` prop on the `RegionDropdown` component limits the listed regions to those that you specify. The
+values are found in the `countryShortCode` value in the [source data package](https://github.com/country-regions/country-region-data/blob/master/data.json).
+Note the order will always be alphabetical.
+
+
+
+---
+
+```tsx
+import React, { useState } from 'react';
+import { CountryDropdown, RegionDropdown } from 'react-country-region-selector';
+
+const RegionWhitelist = () => {
+ const [country, setCountry] = useState('');
+ const [region, setRegion] = useState('');
+
+ return (
+ <>
+ setCountry(val)}
+ whitelist={['CA', 'US']}
+ />
+ setRegion(val)}
+ // highlight-start
+ whitelist={{
+ CA: ['AB', 'BC'],
+ US: ['WA', 'TX'],
+ }}
+ // highlight-end
+ />
+ >
+ );
+};
+
+export default RegionWhitelist;
+```
diff --git a/apps/docs/docs/Demos/ShortcodeLabels.mdx b/apps/docs/docs/Demos/features/ShortcodeLabels.mdx
similarity index 92%
rename from apps/docs/docs/Demos/ShortcodeLabels.mdx
rename to apps/docs/docs/Demos/features/ShortcodeLabels.mdx
index 28fd33c..bfbb9e4 100644
--- a/apps/docs/docs/Demos/ShortcodeLabels.mdx
+++ b/apps/docs/docs/Demos/features/ShortcodeLabels.mdx
@@ -3,7 +3,7 @@ title: Shortcode Labels
sidebar_position: 6
---
-import ShortcodeLabels from '@site/src/components/examples/ShortcodeLabels';
+import ShortcodeLabels from '@site/src/components/demos/features/ShortcodeLabels';
The `CountryDropdown` and `RegionDropdown` fields both let you customize the display values for the
dropdowns. Either `full` (default) or `short`. You can mix and match. Note that this is purely for the _label_.
diff --git a/apps/docs/docs/Demos/ShortcodeValues.mdx b/apps/docs/docs/Demos/features/ShortcodeValues.mdx
similarity index 93%
rename from apps/docs/docs/Demos/ShortcodeValues.mdx
rename to apps/docs/docs/Demos/features/ShortcodeValues.mdx
index b574caf..cd9b03f 100644
--- a/apps/docs/docs/Demos/ShortcodeValues.mdx
+++ b/apps/docs/docs/Demos/features/ShortcodeValues.mdx
@@ -3,7 +3,7 @@ title: Shortcode Values
sidebar_position: 7
---
-import ShortcodeLabels from '@site/src/components/examples/ShortcodeLabels';
+import ShortcodeLabels from '@site/src/components/demos/features/ShortcodeLabels';
The `valueType` prop on both components alters the _value_ of each option to be a short code rather than the full
country or region name, like with the visible label. Note that when you use `valueType` as `short` for the
diff --git a/apps/docs/docs/Demos/features/index.mdx b/apps/docs/docs/Demos/features/index.mdx
new file mode 100644
index 0000000..805d0e8
--- /dev/null
+++ b/apps/docs/docs/Demos/features/index.mdx
@@ -0,0 +1,13 @@
+---
+title: Features
+---
+
+This section demos all the various features of the script. You can read the descriptions in the sidebar in the left if
+that works for you, but here's a simple mapping of prop to demo - in case that's more useful.
+
+| `CountryDropdown` | `RegionDropdown` |
+| --------------------------- | --------------------------- |
+| [`value`](../BasicUsage) | [`value`](../BasicUsage) |
+| [`onChange`](../BasicUsage) | [`onChange`](../BasicUsage) |
+
+[TODO]
diff --git a/apps/docs/docs/Demos/index.mdx b/apps/docs/docs/Demos/index.mdx
new file mode 100644
index 0000000..a62c8e1
--- /dev/null
+++ b/apps/docs/docs/Demos/index.mdx
@@ -0,0 +1,11 @@
+---
+title: Demos
+---
+
+The following pages demo all the features of the script.
+
+- [Basic Usage](./BasicUsage): start here for a quick demonstration of how to use the components.
+- [Features](./Features): this section contains demos of all the available features.
+- [Integrations](./Integrations): by default, the components output by this package output plain HTML `