diff --git a/doc/KNOWN_ISSUES.md b/doc/KNOWN_ISSUES.md index c27b3f698..78f33fe89 100644 --- a/doc/KNOWN_ISSUES.md +++ b/doc/KNOWN_ISSUES.md @@ -6,6 +6,7 @@ 1. [React Native version](#react-native-version) 1. [Android performance](#android-performance) 1. [Unreliable callbacks](#unreliable-callbacks) +1. [Unreliable first item](#unreliable-first-item) 1. [Error with Jest](#error-with-jest) 1. [RTL support (experimental)](#rtl-support-experimental) @@ -53,6 +54,12 @@ Callback handling has been completely revamped in version 3.2.0, in a less hacky If you're using an in-between version, you're in for some trouble since events won't be fired frequently enough (particularly on Android). **We've added a prop `callbackOffsetMargin` to help with this situation.** +## Unreliable first item + +By design, **the `FlatList` component only renders a small chunk if items initially**. + +This means **you may need to rely on inherited props [`getItemLayout`](https://facebook.github.io/react-native/docs/flatlist#getitemlayout) & [`initialScrollIndex`](https://facebook.github.io/react-native/docs/flatlist#initialscrollindex) to get the `firstItem` prop to work properly** (usable from version `3.8.3` on). + ## Error with Jest You might encounter the following error when using the plugin in conjonction with Jest: `TypeError: Cannot read property 'style' of undefined at Object.`. diff --git a/doc/PROPS_METHODS_AND_GETTERS.md b/doc/PROPS_METHODS_AND_GETTERS.md index 95bb8b3c7..64073abdd 100644 --- a/doc/PROPS_METHODS_AND_GETTERS.md +++ b/doc/PROPS_METHODS_AND_GETTERS.md @@ -35,7 +35,7 @@ Prop | Description | Type | Default `callbackOffsetMargin` | Scroll events might not be triggered often enough to get a precise measure and, therefore, to provide a reliable callback. This usually is an Android issue, which might be linked to the version of React Native you're using (see ["Unreliable callbacks"](https://github.com/archriss/react-native-snap-carousel/blob/master/doc/KNOWN_ISSUES.md#unreliable-callbacks)). To work around this, you can define a small margin that will increase the "sweet spot"'s width. The default value should cover most cases, but **you will want to increase it if you experience missed callbacks**. | Number | `5` `enableMomentum` | See [momentum](https://github.com/archriss/react-native-snap-carousel/blob/master/doc/TIPS_AND_TRICKS.md#momentum) | Boolean | `false` `enableSnap` | If enabled, releasing the touch will scroll to the center of the nearest/active item | Boolean | `true` -`firstItem` | Index of the first item to display | Number | `0` +`firstItem` | Index of the first item to display. :warning: **Make sure to use inherited props [`getItemLayout`](https://facebook.github.io/react-native/docs/flatlist#getitemlayout) & [`initialScrollIndex`](https://facebook.github.io/react-native/docs/flatlist#initialscrollindex) if the prop doesn't seem to work**. | Number | `0` `hasParallaxImages` | Whether the carousel contains `` components or not. Required for specific data to be passed to children. | Boolean | `false` `lockScrollTimeoutDuration` | This prop works in conjunction with `lockScrollWhileSnapping`. When scroll is locked, a timer is created in order to release the scroll if something goes wrong with the regular callback handling. **Normally, you shouldn't have to use this prop.** | Number | `1000` `lockScrollWhileSnapping` | Prevent the user from swiping again while the carousel is snapping to a position. This prevents miscellaneous minor issues (inadvertently tapping an item while scrolling, stopping the scrolling animation if the carousel is tapped in the middle of a snap, clunky behavior on Android when short snapping quickly in opposite directions). The only drawback is that enabling the prop hinders the ability to swipe quickly between items as a little pause between swipes is needed. **Note that the prop won't have any effect if `enableMomentum` is set to `true`, since it would otherwise impede the natural and expected behavior.** | Boolean | `false`