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