You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+62-16Lines changed: 62 additions & 16 deletions
Original file line number
Diff line number
Diff line change
@@ -2,12 +2,10 @@
2
2
3
3
A [React](http://facebook.github.io/react/) autosuggest for the Google Maps Places API. You can also define your own suggests as defaults. Works with [Preact](https://github.com/developit/preact), too.
4
4
5
-
6
5
## Demo
7
6
8
7
Live demo: [ubilabs.github.io/react-geosuggest](http://ubilabs.github.io/react-geosuggest/)
9
8
10
-
11
9
## Installation
12
10
13
11
As this component uses the Google Maps Places API to get suggests, you must include the Google Maps Places API in the `<head>` of your HTML:
@@ -44,91 +42,99 @@ The Geosuggest works out of the box by just including it. However, you can custo
44
42
```js
45
43
importGeosuggestfrom'react-geosuggest';
46
44
47
-
<Geosuggest />
45
+
<Geosuggest />;
48
46
```
49
47
50
48
### ES5:
51
49
52
50
```js
53
51
var Geosuggest =require('react-geosuggest').default;
54
52
55
-
<Geosuggest />
53
+
<Geosuggest />;
56
54
```
57
55
58
56
### Properties
59
57
60
58
#### placeholder
59
+
61
60
Type: `String`
62
61
Default: `Search places`
63
62
64
63
The input field will get this placeholder text.
65
64
66
65
#### initialValue
66
+
67
67
Type: `String`
68
68
Default: `''`
69
69
70
70
An initial value for the input, when you want to prefill the suggest.
71
71
72
72
#### className
73
+
73
74
Type: `String`
74
75
Default: `''`
75
76
76
77
Add an additional class to the geosuggest container.
The bounds to use for biasing the suggests. If this is set, `location` and `radius` are ignored.
118
121
119
122
#### country
123
+
120
124
Type: `String` or `Array`
121
125
Default: `null`
122
126
123
127
Restricts predictions to the specified country (ISO 3166-1 Alpha-2 country code, case insensitive). E.g., us, br, au. You can provide a single one, or an array of up to 5 country code strings.
124
128
125
129
#### types
130
+
126
131
Type: `Array`
127
132
Default: `null`
128
133
129
134
The types of predictions to be returned. Four types are supported: `establishment` for businesses, `geocode` for addresses, `(regions)` for administrative regions and `(cities)` for localities. If nothing is specified, all types are returned. Consult the Google Docs for [up to date types](https://developers.google.com/maps/documentation/javascript/reference#AutocompletionRequest).
130
135
131
136
#### fixtures
137
+
132
138
Type: `Array`
133
139
Default: `[]`
134
140
@@ -137,165 +143,196 @@ An array with fixtures (defaults). Each fixture has to be an object with a `labe
137
143
You can also add a `className` key to a fixture. This class will be applied to the fixture item.
138
144
139
145
#### maxFixtures
146
+
140
147
Type: `Number`
141
148
Default: `10`
142
149
143
150
Maximum number of fixtures to render.
144
151
152
+
#### placeDetailFields
153
+
154
+
Type: `Array`
155
+
Default: `null`
156
+
145
157
#### googleMaps
158
+
146
159
Type: `Object`
147
160
Default: `google.maps`
148
161
149
162
In case you want to provide your own Google Maps object, pass it in as googleMaps. The default is the global google maps object.
150
163
151
164
#### ignoreTab
165
+
152
166
Type: `Boolean`
153
167
Default: `false`
154
168
155
169
When the tab key is pressed, the `onSelect` handler is invoked. Set to true to not invoke `onSelect` on tab press.
156
170
157
171
#### ignoreEnter
172
+
158
173
Type: `Boolean`
159
174
Default: `false`
160
175
161
176
When the enter key is pressed, the `onSelect` handler is invoked. Set to true to not invoke `onSelect` on enter press.
162
177
163
178
#### queryDelay
179
+
164
180
Type: `Number`
165
181
Default: `250`
166
182
167
183
Sets the delay in milliseconds after typing before a request will be sent to find suggestions.
168
184
Specify `0` if you wish to fetch suggestions after every keystroke.
169
185
170
186
#### minLength
187
+
171
188
Type: `Number`
172
189
Default: `1`
173
190
174
191
Sets a minimum length of characters before a request will be sent to find suggestions.
175
192
176
193
#### highlightMatch
194
+
177
195
Type: `Boolean`
178
196
Default: `true`
179
197
180
198
Highlights matched text.
181
199
182
200
#### onFocus
201
+
183
202
Type: `Function`
184
203
Default: `function() {}`
185
204
186
205
Gets triggered when the input field receives focus.
187
206
188
207
#### onBlur
208
+
189
209
Type: `Function`
190
210
Default: `function(value) {}`
191
211
192
212
Gets triggered when input field loses focus.
193
213
194
214
#### onChange
215
+
195
216
Type: `Function`
196
217
Default: `function(value) {}`
197
218
198
219
Gets triggered when input field changes the value.
199
220
200
221
#### onKeyDown
222
+
201
223
Type: `Function`
202
224
Default: `function(event) {}`
203
225
204
226
Gets triggered when input field has a key pressed down. This event is triggered before onKeyPress.
205
227
206
228
#### onKeyPress
229
+
207
230
Type: `Function`
208
231
Default: `function(event) {}`
209
232
210
233
Gets triggered when input field gets key press.
211
234
212
235
#### onSuggestSelect
236
+
213
237
Type: `Function`
214
238
Default: `function(suggest) {}`
215
239
216
240
Gets triggered when a suggest got selected. Only parameter is an object with data of the selected suggest. This data is available:
217
241
218
-
*`label` – Type `String` – The label name
219
-
*`placeId` – Type `String` – If it is a preset, equals the `label`. Else it is the Google Maps `placeID`
220
-
*`location` – Type `Object` – The location containing `lat` and `lng`
221
-
*`gmaps` – Type `Object` – *Optional!* The complete response when there was a Google Maps geocode necessary (e.g. no location provided for presets). [Check the Google Maps Reference](https://developers.google.com/maps/documentation/javascript/reference#GeocoderResult) for more information on it’s structure.
242
+
-`label` – Type `String` – The label name
243
+
-`placeId` – Type `String` – If it is a preset, equals the `label`. Else it is the Google Maps `placeID`
244
+
-`location` – Type `Object` – The location containing `lat` and `lng`
245
+
-`gmaps` – Type `Object` – *Optional!* The complete response when there was a Google Maps geocode necessary (e.g. no location provided for presets). [Check the Google Maps Reference](https://developers.google.com/maps/documentation/javascript/reference#GeocoderResult) for more information on it’s structure.
222
246
223
247
#### onUpdateSuggests
248
+
224
249
Type: `Function`
225
250
Default: `function(suggests, activeSuggest) {}`
226
251
227
252
Gets triggered when the suggest list changes. Arguments include the suggest list and the current activeSuggest. Useful if you want to render the list of suggests outside of react-geosuggest.
228
253
229
254
#### onActivateSuggest
255
+
230
256
Type: `Function`
231
257
Default: `function(suggest) {}`
232
258
233
259
Gets triggered when a suggest is activated in the list. Only parameter is an object with data of the selected suggest. This data is available:
234
260
235
-
*`label` – Type `String` – The label name
236
-
*`placeId` – Type `String` – If it is a preset, equals the `label`. Else it is the Google Maps `placeID`
261
+
-`label` – Type `String` – The label name
262
+
-`placeId` – Type `String` – If it is a preset, equals the `label`. Else it is the Google Maps `placeID`
237
263
238
264
#### onSuggestNoResults
265
+
239
266
Type: `Function`
240
267
Default: `function(userInput) {}`
241
268
242
269
Gets triggered when there are no suggest results found
Used to generate a custom label for a suggest. Only parameter is a suggest (google.maps.places.AutocompletePrediction). [Check the Google Maps Reference](https://developers.google.com/maps/documentation/javascript/reference#GeocoderResult) for more information on it’s structure.
249
277
250
278
#### renderSuggestItem
279
+
251
280
Type: `Function`
252
281
Default: `null`
253
282
254
283
Used to customize the inner html of SuggestItem and allows for controlling what properties of the suggest object you want to render. Also a convenient way to add additional styling to different rendered elements within SuggestItem. The function is passed both the suggestion and the user input.
255
284
256
285
#### skipSuggest
286
+
257
287
Type: `Function`
258
288
Default: `function(suggest) {}`
259
289
260
290
If the function returns true then the suggest will not be included in the displayed results. Only parameter is an object with data of the selected suggest. (See above)
261
291
262
292
#### autoActivateFirstSuggest
293
+
263
294
Type: `Boolean`
264
295
Default: `false`
265
296
266
297
Automatically activate the first suggestion as you type. If false, the exact term(s) in the input will be used when searching and may return a result not in the list of suggestions.
267
298
268
299
#### label
300
+
269
301
Type: `String`
270
302
Default: `null`
271
303
272
304
If the `label` and a `id` prop (see "Others") were supplied, a `<label>` tag with the passed label text will be rendered. The `<label>` element's `for` attribute will correctly point to the `id` of the `<input>` element.
273
305
274
306
#### suggestsClassName
307
+
275
308
Type: `String`
276
309
Default: `''`
277
310
278
311
Add an additional class to suggest list.
279
312
280
313
#### suggestsHiddenClassName
314
+
281
315
Type: `String`
282
316
Default: `null`
283
317
284
318
Additional `className` to toggle as the list of suggestions changes visibility.
285
319
286
320
#### suggestItemClassName
321
+
287
322
Type: `String`
288
323
Default: `''`
289
324
290
325
Add an additional class to suggest item.
291
326
292
327
#### suggestItemActiveClassName
328
+
293
329
Type: `String`,
294
330
Default: `null`
295
331
296
332
Additional `className` to add when a suggestion item is active.
297
333
298
334
#### autoComplete
335
+
299
336
Type: `String`,
300
337
Default: `nope`
301
338
@@ -307,23 +344,28 @@ All [allowed attributes for `input[type="text"]`](https://github.com/ubilabs/rea
307
344
All [DOM clipboard events](https://facebook.github.io/react/docs/events.html#clipboard-events).
308
345
All [DOM mouse events](https://facebook.github.io/react/docs/events.html#mouse-events) except for drag & drop.
309
346
310
-
311
347
### Exposed component functions
348
+
312
349
These functions are accessible by setting "ref" on the component (see example below)
313
350
314
351
#### focus()
352
+
315
353
Call `focus` to focus on the element. The suggest list will be expanded with the current suggestions.
316
354
317
355
#### blur()
356
+
318
357
Call `blur` to blur (unfocus) the element. The suggest list will be closed.
319
358
320
359
#### update(value)
360
+
321
361
It is possible to update the value of the input contained within the GeoSuggest component by calling the `update` function with a new desired `value` of the type String.
322
362
323
363
#### clear()
364
+
324
365
It is also possible to clear the value of the input contained within the GeoSuggest component by calling the `clear` function.
325
366
326
367
#### selectSuggest()
368
+
327
369
Same effect as hitting `enter` (will geocode the text inside of the input).
328
370
329
371
### Example
@@ -383,22 +425,26 @@ This component uses [BEM](http://csswizardry.com/2013/01/mindbemding-getting-you
383
425
### Note:
384
426
385
427
The `geosuggest__suggests--hidden` class is added to hide the suggestion list. You should copy the style below into your CSS file.
428
+
386
429
```css
387
430
.geosuggest__suggests--hidden {
388
431
max-height: 0;
389
432
overflow: hidden;
390
433
border-width: 0;
391
434
}
392
435
```
436
+
393
437
The above class is added whenever the suggestion list needs to be hidden. This occurs when the user selects an item from the list or when the user triggers the `blur` event on the input.
394
438
395
439
Similarly, you need to have the class `geosuggest__item--active` similar to this:
440
+
396
441
```css
397
442
.geosuggest__item--active {
398
443
background: #267dc0;
399
444
color: #fff;
400
445
}
401
446
```
447
+
402
448
to see what item is selected, f.ex. when using the arrow keys to navigate the suggestion list.
0 commit comments