|
| 1 | +# `native-prompt` |
| 2 | +Create native prompts with Node.js and Electron |
| 3 | + |
| 4 | +# What is this? |
| 5 | +While `alert` and `confirm` are both supported in Electron, `prompt` isn't (see [this issue](https://github.com/electron/electron/issues/472)). `native-prompt` aims to fix this by allowing you to create prompt boxes that are native to the user's OS. As an added bonus, it also works in Node.js. |
| 6 | + |
| 7 | +# Screenshots |
| 8 | +## Windows |
| 9 | + |
| 10 | +## Linux |
| 11 | + |
| 12 | +## MacOS |
| 13 | + |
| 14 | + |
| 15 | +# Installation |
| 16 | +### Through [NPM](https://www.npmjs.com/package/native-prompt): |
| 17 | +>`npm i native-prompt` |
| 18 | +### ...or the long way: |
| 19 | +>`npm install native-prompt@latest --save` |
| 20 | +
|
| 21 | +# Usage |
| 22 | +## Synopsis |
| 23 | +```js |
| 24 | +prompt (title, body, options) |
| 25 | +``` |
| 26 | +### `title:string` |
| 27 | +>The title you want to display at the top of the window |
| 28 | +### `body:string` |
| 29 | +>Any helpful text to go inside the message box |
| 30 | +### `options: { defaultText?: string; mask?: boolean; okButtonLabel?: string; cancelButtonLabel?: string }` |
| 31 | +>Any (optional) extra options (see below) |
| 32 | +
|
| 33 | +## Options |
| 34 | +### `defaultText?: string` |
| 35 | +>The text you want to already be in the input box beforehand |
| 36 | +### `mask?: boolean` |
| 37 | +>Whether you want the box to have a hidden input |
| 38 | +### `okButtonLabel?: string` |
| 39 | +>The label for the "ok" button, it only works on windows and linux and by default in linux it is not set and in windows it is set as "Ok" |
| 40 | +### `cancelButtonLabel?: string` |
| 41 | +>The label for the "cancel" button, it only works on windows and linux and by default in linux it is not set and in windows it is set as "Cancel" |
| 42 | +
|
| 43 | +## Examples |
| 44 | +### Importing |
| 45 | +#### Javascript |
| 46 | +```js |
| 47 | +const prompt = require('native-prompt') |
| 48 | +``` |
| 49 | +#### Typescript |
| 50 | +```ts |
| 51 | +import prompt from 'native-prompt' |
| 52 | +``` |
| 53 | +--- |
| 54 | +### Async function usage |
| 55 | +```js |
| 56 | +(async () => { |
| 57 | + const text = await prompt("This is a title.", "What would you really like to see next?", { defaultText: "Nothing" }); |
| 58 | + if (text) { |
| 59 | + // Do something with the input |
| 60 | + } else { |
| 61 | + // The user either clicked cancel or left the space blank |
| 62 | + } |
| 63 | +})() |
| 64 | +``` |
| 65 | +### Regular promise usage |
| 66 | +```js |
| 67 | +prompt("This is a title.", "What would you really like to see next?", { defaultText: "Nothing" }).then(text => { |
| 68 | + if (text) { |
| 69 | + // Do something with the input |
| 70 | + } else { |
| 71 | + // The user either clicked cancel or left the space blank |
| 72 | + } |
| 73 | +}) |
| 74 | +``` |
| 75 | + |
| 76 | +### Masked textbox example |
| 77 | +```js |
| 78 | +(async () => { |
| 79 | + const password = await prompt("Login", "Enter your password to log back in.", { mask: true }); |
| 80 | + if (isCorrectPassword(password)) { |
| 81 | + // Log the user in |
| 82 | + } else { |
| 83 | + // The user's entered their username or password incorrect |
| 84 | + } |
| 85 | +})() |
| 86 | +``` |
| 87 | + |
| 88 | +### Ok and Cancel buttons modified example |
| 89 | +```js |
| 90 | +(async () => { |
| 91 | + const text = await prompt("Your Name", "Write your name.", { okButtonLabel: "Submit", cancelButtonLabel: "Abort" }); |
| 92 | + if (text) { |
| 93 | + // Do something with the input |
| 94 | + } else { |
| 95 | + // The user either clicked cancel or left the space blank |
| 96 | + } |
| 97 | +})() |
| 98 | +``` |
| 99 | + |
| 100 | +# Notes |
| 101 | +* If you plan on using `asar` to package your electron app, make sure to read [this](https://github.com/ssight/native-prompt/wiki/Usage-with-asar) |
| 102 | +* For differences between 1.x and 2.x, see [this](https://github.com/ssight/native-prompt/wiki/Differences-between-1.x-and-2.x) wiki page. |
0 commit comments