docs: add section about nativeBreakpointsMode

jpudysz · Jan 30, 2025 · d1533c4 · d1533c4
1 parent e76679c
commit d1533c4
Show file tree

Hide file tree

Showing 5 changed files with 21 additions and 8 deletions.
diff --git a/docs/.astro/settings.json b/docs/.astro/settings.json
@@ -1,5 +1,5 @@
 {
 	"_variables": {
-		"lastUpdateCheck": 1737126711469
+		"lastUpdateCheck": 1738238865697
 	}
 }
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
@@ -73,7 +73,7 @@ export default defineConfig({
 					items: [
 						{ label: 'Introduction', slug: 'v3/start/introduction' },
                         { label: 'Getting started', slug: 'v3/start/getting-started' },
-                        { label: 'Configuration', slug: 'v3/start/configuration' },
+                        { label: 'Configuration', slug: 'v3/start/configuration', badge: 'Updated' },
                         { label: 'New features', slug: 'v3/start/new-features' },
                         { label: 'Look under the hood', slug: 'v3/start/how-unistyles-works' },
                         { label: 'Migration guide', slug: 'v3/start/migration-guide' }
@@ -82,12 +82,12 @@ export default defineConfig({
                 {
                     label: 'Guides',
                     items: [
-                        { label: 'Merging styles', slug: 'v3/guides/merging-styles', badge: 'New!' },
+                        { label: 'Merging styles', slug: 'v3/guides/merging-styles', badge: 'Updated' },
                         { label: 'Theming', slug: 'v3/guides/theming' },
                         { label: 'Avoiding Keyboard', slug: 'v3/guides/avoiding-keyboard' },
                         { label: 'Expo Router', slug: 'v3/guides/expo-router' },
                         { label: 'Custom web', slug: 'v3/guides/custom-web', badge: 'WIP' },
-                        { label: 'Server side rendering', slug: 'v3/guides/server-side-rendering', badge: 'New!' },
+                        { label: 'Server side rendering', slug: 'v3/guides/server-side-rendering' },
                     ]
                 },
                 {
@@ -102,11 +102,11 @@ export default defineConfig({
                         { label: 'Variants', slug: 'v3/references/variants' },
                         { label: 'Compound Variants', slug: 'v3/references/compound-variants' },
                         { label: 'Web styles', slug: 'v3/references/web-styles' },
-                        { label: 'Web Only Features', slug: 'v3/references/web-only', badge: 'Updated' },
+                        { label: 'Web Only Features', slug: 'v3/references/web-only' },
                         { label: 'Scoped theme', slug: 'v3/references/scoped-theme' },
-                        { label: 'Update 3rd party views', slug: 'v3/references/3rd-party-views', badge: 'New!' },
+                        { label: 'Update 3rd party views', slug: 'v3/references/3rd-party-views' },
                         { label: 'withUnistyles', slug: 'v3/references/with-unistyles' },
-                        { label: 'useUnistyles', slug: 'v3/references/use-unistyles', badge: 'New!' },
+                        { label: 'useUnistyles', slug: 'v3/references/use-unistyles' },
                         { label: 'Display and Hide', slug: 'v3/references/display-hide' },
                         { label: 'Edge to edge', slug: 'v3/references/edge-to-edge' },
                         { label: 'Dimensions', slug: 'v3/references/dimensions' },

diff --git a/docs/src/content/docs/v3/guides/merging-styles.mdx b/docs/src/content/docs/v3/guides/merging-styles.mdx
@@ -44,6 +44,10 @@ When you see this warning, your component will render correctly, but any new eve
 
 It's critical to ship Unistyles 3.0 apps without this warning, as it can cause unexpected behavior.
 
+<Aside title="Reanimated" type="caution">
+By default `Animated` components will flatten your styles array. This means that you can only pass single unistyle to `Animated` components, otherwise you'll get a warning from above.
+</Aside>
+
 ### Spreading a single Unistyle
 
 Another problematic case is spreading a single Unistyle and merging it, e.g., with inline styles:

diff --git a/docs/src/content/docs/v3/references/breakpoints.mdx b/docs/src/content/docs/v3/references/breakpoints.mdx
@@ -136,6 +136,14 @@ const styles = StyleSheet.create(theme => ({
 }))
 ```
 
+### Pixel/Point mode for native breakpoints
+
+By default, Unistyles will use `pixels` for native breakpoints. This means that the breakpoints and [mq](/v3/references/media-queries) will be computed based on mobile screen pixels.
+You can change this behavior by setting `nativeBreakpointsMode` to `points` in your [configuration](/v3/start/configuration#settings-optional).
+
+If `nativeBreakpointsMode` is set to `points` all breakpoints and `mq` will be computed based on mobile screen points (screen in pixels divided by pixel ratio).
+
+
 ### Show/Hide your components based on breakpoints
 
 In order to show or hide your components based on the screen size, you can leverage the `mq` utility and one of the two built-in components: `Display` and `Hide`.

diff --git a/docs/src/content/docs/v3/start/configuration.mdx b/docs/src/content/docs/v3/start/configuration.mdx
@@ -73,11 +73,12 @@ const breakpoints = {
 
 ### Settings (Optional)
 
-The `Settings` object has been simplified, and in the most recent version, it supports only three properties:
+The `Settings` object has been simplified, and in the most recent version, it supports only four properties:
 
 - **`adaptiveThemes`** – a boolean that enables or disables adaptive themes [learn more](/v3/guides/theming#adaptive-themes)
 - **`initialTheme`** – a string or a synchronous function that sets the initial theme
 - **`CSSVars`** – a boolean that enables or disables CSS variables (defaults to `true`) [learn more](/v3/references/web-only#css-variables)
+- **`nativeBreakpointsMode`** - iOS/Android only. User preferred mode for breakpoints. Can be either `points` or `pixels` (defaults to `pixels`) [learn more](/v3/references/breakpoints#pixelpoint-mode-for-native-breakpoints)
 
 ```tsx title="unistyles.ts"
 const settings = {