Skip to content

Commit dfd62d6

Browse files
jamesisaacjamesisaac
committed
Update docs
1 parent 8fb74b1 commit dfd62d6

2 files changed

Lines changed: 90 additions & 54 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
## 1.1.0
2+
3+
* Add an `all` prop for more concisely/explicitly setting both platforms to the same effect.
4+
* Improve Flow types.
5+
6+
## 1.0.2
7+
8+
* Just resorted to `mixed` for `outerStyle` Flow type, as the last attempt was still insufficient to cover everything which RN allows.
9+
10+
## 1.0.1
11+
12+
* Expanded Flow allowed types for `outerStyle`
13+
14+
## 1.0.0
15+
16+
First public release, with formalized API.

‎README.md‎

Lines changed: 74 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,40 @@
11
# react-native-touchable-safe
22

33
[![npm version](https://img.shields.io/npm/v/react-native-touchable-safe.svg)](https://www.npmjs.com/package/react-native-touchable-safe)
4+
[![Circle CI Status](https://circleci.com/gh/jamesisaac/react-native-touchable-safe.svg?style=shield)](https://circleci.com/gh/jamesisaac/react-native-touchable-safe)
45
[![license](https://img.shields.io/github/license/jamesisaac/react-native-touchable-safe.svg)](https://opensource.org/licenses/MIT)
56
[![npm downloads](https://img.shields.io/npm/dm/react-native-touchable-safe.svg)](https://www.npmjs.com/package/react-native-touchable-safe)
67

7-
Consistent view hierarchy and API for React Native `Touchable*` components.
8+
A single easy-to-use `<Touchable>` component, which harnesses the power of all React Native's `Touchable*` components.
89

9-
As it stands, `TouchableOpacity` and `TouchableHighlight` wrap their children
10-
in a `View`, whereas `TouchableNativeFeedback` and `TouchableWithoutFeedback`
11-
do not. This can lead to headaches and platform-specific bugs when trying to
12-
create advanced Flexbox layouts with different touchable styles on Android/iOS.
10+
* Simple API that bridges the differences between RN's various `Touchable*` types.
11+
* A consistent `View` hierarchy, to avoid tricky layout issues when switching between `Touchable*` types.
12+
* Handling the incompatability of ripple customisation on Android API level < 21.
13+
14+
## Motivation
15+
16+
As it stands, `TouchableOpacity` and `TouchableHighlight` wrap their children in a `View`, whereas `TouchableNativeFeedback` and `TouchableWithoutFeedback`
17+
do not.
18+
This can lead to headaches and platform-specific bugs when trying to create advanced Flexbox layouts with different touchable styles on Android/iOS.
1319
An example of this is available here: https://snack.expo.io/ry6kXjX8W
1420

15-
This component also provides a simpler API, where alternating the component
16-
used per platform is as simple as:
21+
This library makes the situation consistent and easy to reason about:
22+
23+
* `<Touchable>` **always** introduces another view in the hierarchy, which can have its layout customised with `outerStyle`.
24+
* `<Touchable>` **always** must only have one child, which it applies its effect (e.g. opacity) to natively.
25+
26+
## Installation
27+
28+
```bash
29+
$ npm install --save react-native-touchable-safe
30+
31+
# Or, with Yarn
32+
$ yarn add react-native-touchable-safe
33+
```
34+
35+
## Getting started
36+
37+
This component provides a simple API, where alternating the component used per platform is as simple as:
1738

1839
```js
1940
return (
@@ -23,47 +44,35 @@ return (
2344
)
2445
```
2546

26-
In fact, these are the default behaviours, so simply `<Touchable>` is enough to
27-
achieve this effect. The android/ios props only need to be used when deviating
28-
from the defaults.
29-
30-
This component also handles the incompatability of ripple customisation on
31-
Android API level < 21.
32-
33-
## Installation
34-
35-
```bash
36-
$ npm install --save react-native-touchable-safe
37-
```
47+
In fact, these are the default behaviours, so simply `<Touchable>` is enough to achieve this effect.
48+
The android/ios props only need to be used when deviating from the defaults.
3849

3950
## Props
4051

41-
If you don't want to use the defaults (`TouchableNativeFeedback` on Android
42-
and `TouchableOpacity` on iOS), you can specify another type:
52+
If you don't want to use the defaults (`TouchableNativeFeedback` on Android and `TouchableOpacity` on iOS), you can specify another type.
53+
Use `all` to set all platforms to the same effect, or `ios` and `android` to differentiate it per platform.
4354

55+
* **`all?`**: `'opacity' | 'highlight' | 'without'`
4456
* **`ios?`**: `'opacity' | 'highlight' | 'without'` - (default: `'opacity'`)
4557
* **`android?`**: `'native' | 'opacity' | 'highlight' | 'without'` - (default: `'native'`)
4658

4759
Some very common behaviours used by all touchable types:
4860

4961
* **`onPress?`**: `() => void`
5062
* **`outerStyle?`**: `Object | number` - Style to pass to the outer `View`
51-
component which wraps every type of touchable component. Typically used to
63+
component which wraps every type of touchable component. Typically used to
5264
specify things like `<Touchable outerStyle={{ flex: 1 }}>`.
5365
* **`outerProps?`**: `Object` - Similar to `outerStyle`, but lets you set any
5466
props (although `style` is the main use case).
5567
* **`disabled?`**: `boolean` - Remove any touch functionality and feedback.
5668

57-
Seeing as setting a custom native ripple requires calling
58-
`TouchableNativeFeedback.Ripple`, the following top-level convenience props can
59-
be used to quickly customise the ripple:
69+
Seeing as setting a custom native ripple requires calling `TouchableNativeFeedback.Ripple`, the following top-level convenience props can be used to quickly customise the ripple:
6070

6171
* **`nativeBorderless?`**: `boolean` - For `android="native"`, should the
6272
ripple effect be borderless.
6373
* **`nativePressColor?`**: `string` - (default: `'rgba(0, 0, 0, .1)'`) - For `android="native"`, what color should the ripple be.
6474

65-
Any props which you only want passed to one type of touchable component can be
66-
controlled with the following props.
75+
Any props which you only want passed to one type of touchable component can be controlled with the following props.
6776

6877
* **`nativeProps?`**: `Object` - Any props to pass on to a
6978
`TouchableNativeFeedback` component.
@@ -73,9 +82,9 @@ controlled with the following props.
7382
`TouchableHighlight` component.
7483
* **`withoutProps?`**: `Object` - Any props to pass on to a
7584
`TouchableWithoutFeedback` component.
76-
85+
7786
And finally, anything else will be passed down to all touchable components.
78-
87+
7988
## Examples
8089

8190
### Defaults
@@ -88,7 +97,11 @@ import Touchable from 'react-native-touchable-safe'
8897
import MyLabel from './MyLabel'
8998

9099
export default () => (
91-
<Touchable onPress={() => { console.log('Pressed') }}>
100+
<Touchable
101+
onPress={() => {
102+
console.log('Pressed')
103+
}}
104+
>
92105
<MyLabel />
93106
</Touchable>
94107
)
@@ -102,49 +115,56 @@ A row of different styled buttons, which all behave consistently
102115
import React from 'react'
103116
import { StyleSheet } from 'react-native'
104117
import Touchable from 'react-native-touchable-safe'
105-
import MyLabel from './MyLabel'
118+
import MyButton from './MyButton'
106119

107-
export default ({ disableD }) => (
120+
export default ({ disabled }) => (
108121
<View style={styles.row}>
109122
{/* Android: native, iOS: highlight */}
110123
<Touchable
111124
ios="highlight"
112-
onPress={() => { console.log('Pressed A') }}
113-
outerStyle={styles.buttonOuter}
125+
onPress={() => {
126+
console.log('Pressed A')
127+
}}
128+
outerStyle={styles.touchWrap}
114129
nativeBorderless
115130
nativePressColor="rgba(0, 0, 255, .5)"
116131
>
117-
<MyLabel title="A" />
132+
<MyButton title="A" />
118133
</Touchable>
119-
134+
120135
{/* Both: opacity (50% opacity) */}
121136
<Touchable
122-
android="opacity"
123-
onPress={() => { console.log('Pressed B') }}
124-
outerStyle={styles.buttonOuter}
125-
opacityProps={{ activeOpacity: .5 }}
137+
all="opacity"
138+
onPress={() => {
139+
console.log('Pressed B')
140+
}}
141+
outerStyle={styles.touchWrap}
142+
opacityProps={{ activeOpacity: 0.5 }}
126143
>
127-
<MyLabel title="B" />
144+
<MyButton title="B" />
128145
</Touchable>
129-
146+
130147
{/* Both: no feedback */}
131148
<Touchable
132-
ios="without"
133-
android="without"
134-
onPress={() => { console.log('Pressed C') }}
135-
outerStyle={styles.buttonOuter}
149+
all="without"
150+
onPress={() => {
151+
console.log('Pressed C')
152+
}}
153+
outerStyle={styles.touchWrap}
136154
>
137-
<MyLabel title="C" />
155+
<MyButton title="C" />
138156
</Touchable>
139-
157+
140158
{/* Both: defaults, disabled based on prop */}
141159
<Touchable
142-
onPress={() => { console.log('Pressed D') }}
143-
outerStyle={styles.buttonOuter}
144-
disabled={disableD}
160+
onPress={() => {
161+
console.log('Pressed D')
162+
}}
163+
outerStyle={styles.touchWrap}
164+
disabled={disabled}
145165
>
146166
{/* Visual styling of disabled elements handled manually */}
147-
<MyLabel title="D" greyedOut={disableD} />
167+
<MyButton title="D" greyedOut={disabled} />
148168
</Touchable>
149169
</View>
150170
)
@@ -155,9 +175,9 @@ const styles = StyleSheet.create({
155175
alignItems: 'top',
156176
height: 200,
157177
},
158-
buttonOuter: {
178+
touchWrap: {
159179
flex: 1,
160180
height: 100,
161181
},
162182
})
163-
```
183+
```

0 commit comments

Comments
 (0)