1 | # react-a-gate
|
2 |
|
3 | [![version](https://img.shields.io/npm/v/react-a-gate.svg)](https://www.npmjs.com/package/react-a-gate)
|
4 | [![install-size](https://packagephobia.now.sh/badge?p=react-a-gate)](https://packagephobia.now.sh/result?p=react-a-gate)
|
5 | [![license](https://img.shields.io/npm/l/react-a-gate.svg)](https://github.com/bonavida/react-a-gate/blob/master/LICENSE)
|
6 |
|
7 | ## Overview
|
8 |
|
9 | `react-a-gate` is a React library for modals, tooltips and popovers. It uses the new React feature called [Portals](https://reactjs.org/docs/portals.html). Basically, a portal (ehem... a gate) allows you to render an element of a child component outside the DOM hierarchy by creating another top-level tree and injecting this component inside it.
|
10 |
|
11 | ## Requirements
|
12 |
|
13 | - node 12.xx.x
|
14 | - npm 6.x.x
|
15 |
|
16 | ## Installation
|
17 |
|
18 | ```sh
|
19 | npm install react-a-gate
|
20 | ```
|
21 |
|
22 | or
|
23 |
|
24 | ```sh
|
25 | yarn add react-a-gate
|
26 | ```
|
27 |
|
28 | ## Usage
|
29 |
|
30 | ### Modal
|
31 |
|
32 | 1 . Import `ModalGate` after the installation.
|
33 |
|
34 | ```js
|
35 | import { ModalGate } from 'react-a-gate';
|
36 | ```
|
37 |
|
38 | 2 . Add the ModalGate component into your JSX code.
|
39 |
|
40 | ```js
|
41 | const App = () => {
|
42 | const [isOpen, setIsOpen] = useState(false);
|
43 |
|
44 | const openModal = () => setIsOpen(true);
|
45 | const closeModal = () => setIsOpen(false);
|
46 |
|
47 | return (
|
48 | <>
|
49 | <button className="App-button" onClick={openModal}>
|
50 | Open modal
|
51 | </button>
|
52 | <ModalGate id="app_modal" isOpen={isOpen} onClose={closeModal}>
|
53 | <>
|
54 | <div>This is a modal</div>
|
55 | <button className="App-button" onClick={closeModal}>
|
56 | Close modal
|
57 | </button>
|
58 | </>
|
59 | </ModalGate>
|
60 | </>
|
61 | );
|
62 | };
|
63 | ```
|
64 |
|
65 | You can also use a custom React component to be rendered inside the modal, like the example below:
|
66 |
|
67 | ```js
|
68 | const Text = () => <div>This is some text</div>;
|
69 |
|
70 | const App = () => {
|
71 | // ...
|
72 | <ModalGate id="app_modal" isOpen={isOpen} onClose={closeModal}>
|
73 | <Text />
|
74 | </ModalGate>;
|
75 | // ...
|
76 | };
|
77 | ```
|
78 |
|
79 | #### Props
|
80 |
|
81 | | Property | Type | Default | Description |
|
82 | | --------------------- | -------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
83 | | id | String | - | Identificator for the modal.<br>_Required_. |
|
84 | | rootId | String | `portal-root` | Identificator for the portal. If you already have a different root included in your HTML code, just put here the element id. If not, a new one will be created. |
|
85 | | className | String | - | Property used to override the default CSS styles with custom ones. |
|
86 | | isOpen | Boolean | `false` | Property used to show and hide the modal.<br>_Required_. |
|
87 | | closeWhenClickOutside | Boolean | `true` | Enable or disable the closing of the modal when the user clicks outside. |
|
88 | | onClose | Function | - | Function that triggers the closing of the modal. It is used to close the modal when the user clicks outside the modal and when the user pressed the Escape key.<br>_Required_. |
|
89 |
|
90 | ### Tooltip
|
91 |
|
92 | 1 . Import `TooltipGate` after the installation.
|
93 |
|
94 | ```js
|
95 | import { TooltipGate } from 'react-a-gate';
|
96 | ```
|
97 |
|
98 | 2 . Add the TooltipGate component into your JSX code.
|
99 |
|
100 | ```js
|
101 | const App = () => (
|
102 | <TooltipGate content="This is some text" place="top">
|
103 | <button className="App-button">Hover me</button>
|
104 | </TooltipGate>
|
105 | );
|
106 | ```
|
107 |
|
108 | You can also use a custom React component to be rendered inside the tooltip, like the example below:
|
109 |
|
110 | ```js
|
111 | const Text = () => <div>This is some text</div>;
|
112 |
|
113 | const App = () => {
|
114 | <TooltipGate content={<Text />} place="top">
|
115 | <button className="App-button">Hover me</button>
|
116 | </TooltipGate>;
|
117 | };
|
118 | ```
|
119 |
|
120 | #### Props
|
121 |
|
122 | | Property | Type | Default | Description |
|
123 | | --------- | -------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
124 | | rootId | String | 'portal-root' | Identificator for the portal. If you already have a different root included in your HTML code, just put here the element id. If not, a new one will be created. |
|
125 | | className | String | - | Property used to override the default CSS styles with custom ones. It also overrides the current selected theme. |
|
126 | | content | String / JSX Element | - | Content that will be rendered inside the tooltip. It can be a simple string or a custom React component.<br>_Required_. |
|
127 | | place | String | `top` | Property to set where the tooltip will be placed.<br>**Accepted values:** `top`, `bottom`, `left` and `right`. |
|
128 | | theme | String | `dark` | Property to set an already defined theme.<br>**Accepted values:** `light` and `dark`. |
|
129 | | offset | Number | `10` | Distance between the trigger element and the tooltip. |
|
130 | | children | ReactNode | - | The trigger element. It can be an HTMLElement or any custom React component. <br>_Required_. |
|
131 |
|
132 | ### Popover
|
133 |
|
134 | 1 . Import `PopoverGate` after the installation.
|
135 |
|
136 | ```js
|
137 | import { PopoverGate } from 'react-a-gate';
|
138 | ```
|
139 |
|
140 | 2 . Add the PopoverGate component into your JSX code.
|
141 |
|
142 | ```js
|
143 | const App = () => (
|
144 | <PopoverGate content="This is some text" place="top">
|
145 | <button className="App-button">Click me</button>
|
146 | </PopoverGate>
|
147 | );
|
148 | ```
|
149 |
|
150 | You can also use a custom React component to be rendered inside the popover, like the example below:
|
151 |
|
152 | ```js
|
153 | const Text = () => <div>This is some text</div>;
|
154 |
|
155 | const App = () => {
|
156 | <PopoverGate content={<Text />} place="top">
|
157 | <button className="App-button">Click me</button>
|
158 | </PopoverGate>;
|
159 | };
|
160 | ```
|
161 |
|
162 | #### Props
|
163 |
|
164 | | Property | Type | Default | Description |
|
165 | | --------------------- | -------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
166 | | rootId | String | 'portal-root' | Identificator for the portal. If you already have a different root included in your HTML code, just put here the element id. If not, a new one will be created. |
|
167 | | className | String | - | Property used to override the default CSS styles with custom ones. |
|
168 | | content | String / JSX Element | - | Content that will be rendered inside the popover. It can be a simple string or a custom React component.<br>_Required_. |
|
169 | | place | String | `top` | Property to set where the popover will be placed.<br>**Accepted values:** `top`, `bottom`, `left` and `right`. |
|
170 | | mode | String | `click` | Property to set the mode of the popover. `'click'` mode will open and close the popover when the user clicks at the trigger element, and the `'hover'` mode will open and close the popover when the user hovers in and out the trigger element.<br>**Accepted values:** `click` and `hover`. |
|
171 | | closeWhenClickOutside | Boolean | `true` | Enable or disable the closing of the popover when the user clicks outside. |
|
172 | | theme | String | `dark` | Property to set an already defined theme.<br>**Accepted values:** `light` and `dark`. |
|
173 | | offset | Number | `10` | Distance between the trigger element and the popover. |
|
174 | | children | ReactNode | - | The trigger element. It can be an HTMLElement or any custom React component. <br>_Required_. |
|
175 |
|
176 | ### How to override CSS styles
|
177 |
|
178 | Each component has a few styles by default. In case you want to override them, here are the main classes you need to override on your project:
|
179 |
|
180 | #### Modal
|
181 |
|
182 | ```
|
183 | modal__backdrop
|
184 | > modal__content
|
185 | modal__backdrop--active
|
186 | > modal__content
|
187 | ```
|
188 |
|
189 | #### Tooltip
|
190 |
|
191 | ```
|
192 | tooltip__container
|
193 | tooltip__arrow
|
194 | tooltip__arrow-border
|
195 | tooltip__inner
|
196 | ```
|
197 |
|
198 | In case you want to customize the colors of the tooltip, here's an example of what you need to do:
|
199 |
|
200 | ```scss
|
201 | .red {
|
202 | .tooltip__inner {
|
203 | background-color: #ac2121;
|
204 | border: 1px solid #700404;
|
205 | }
|
206 |
|
207 | .tooltip__arrow {
|
208 | border-color: #ac2121;
|
209 | }
|
210 |
|
211 | .tooltip__arrow-border {
|
212 | border-color: #700404;
|
213 | }
|
214 | }
|
215 | ```
|
216 |
|
217 | ```jsx
|
218 | <TooltipGate content="This is some text" className="red">
|
219 | <button className="App-button">Hover me</button>
|
220 | </TooltipGate>
|
221 | ```
|
222 |
|
223 | #### Popover
|
224 |
|
225 | ```
|
226 | popover__container
|
227 | popover__arrow
|
228 | popover__arrow-border
|
229 | popover__inner
|
230 | ```
|
231 |
|
232 | In case you want to customize the colors of the popover, here's an example of what you need to do:
|
233 |
|
234 | ```scss
|
235 | .red {
|
236 | .popover__inner {
|
237 | background-color: #ac2121;
|
238 | border: 1px solid #700404;
|
239 | }
|
240 |
|
241 | .popover__arrow {
|
242 | border-color: #ac2121;
|
243 | }
|
244 |
|
245 | .popover__arrow-border {
|
246 | border-color: #700404;
|
247 | }
|
248 | }
|
249 | ```
|
250 |
|
251 | ```jsx
|
252 | <PopoverGate content="This is some text" className="red">
|
253 | <button className="App-button">Click me</button>
|
254 | </PopoverGate>
|
255 | ```
|