|
| 1 | +# Button |
| 2 | +Handles buttons and button-like links (components that look like buttons, but |
| 3 | +behave as links) in the same uniform manner. |
| 4 | + |
| 5 | +[Examples](#examples) |
| 6 | + |
| 7 | +**Why?** — Some buttons in our applications, although they look like |
| 8 | +regular buttons, should behave as external (to different apps/webpages) or |
| 9 | +internal (to different routes inside the app) links. Often, there is a need to |
| 10 | +switch between this link-like and the true button behavior as the development |
| 11 | +goes. The `<Button>` button component separates button styling from its logic, |
| 12 | +helping to switch these behaviors without caring about styling, and update the |
| 13 | +styling without caring about functionality. |
| 14 | + |
| 15 | +Under the hood, a `<Button>` is rendered in one of the three ways: |
| 16 | +1. When the `<Button>` is disabled it is rendered as `<div>` element with |
| 17 | +button content, which allows to style disabled buttons the same way, whether |
| 18 | +they are true or buttons or button-like links; |
| 19 | +2. Otherwise, if the `<Button>` has `to` property set it is rendered as |
| 20 | +[`<Link>`](link-and-navlink.md) (in this case it accepts all other props a |
| 21 | +`<Link>` can accept). It helps to properly handle transitions both to external |
| 22 | +URLs, and to other routes within the app (these are handled via the React |
| 23 | +Router's mechanics, without reloading the app); |
| 24 | +3. Otherwise the `<Button>` is rendered as a regular HTML `<button>` (we could |
| 25 | +just use the `<Link>` in this case as well, but rendering and handling the |
| 26 | +`<button>` is a bit more efficient. |
| 27 | + |
| 28 | +### Button Properties |
| 29 | +- **`active`** — *Boolean* — Optional. When *true* the button is |
| 30 | +rendered in active state, even if it is not active otherwise; |
| 31 | +- **`disabled`** — *Boolean* — Optional. When *true* the button is |
| 32 | +disabled; |
| 33 | +- **`enforceA`** — *Boolean* — Optional. When the button is rendered |
| 34 | +as `<Link>` this prop enforces it to be rendered as a simple `<a>` element (thus |
| 35 | +being treated as an external link); |
| 36 | +- **`onClick`** — *Function* — Optional. *onClick* event handler; |
| 37 | +- **`onMouseDown`** — *Function* — Optional. *onMouseDown* event |
| 38 | +handler; |
| 39 | +- **`opneNewTab`** — *Boolean* — Optional. When the button is |
| 40 | +rendered as `<Link>` this property tells to open the link in a new tab; |
| 41 | +- **`replace`** — *Boolean* — Optional. When the button is rendered |
| 42 | +as `<Link>`, and the URL is internal, this property tells that the new route |
| 43 | +should replace the last record in the browser's history, rather than be pushed |
| 44 | +as a new entry into the history stack; |
| 45 | +- **`size`** — *String* — Optional. Button size. If specified, and |
| 46 | +`theme[size]` is defined, `theme[size]` class is added to the root element of |
| 47 | +the button. It is supposed to control button size, and although any values can |
| 48 | +be used, it is recommended to stick with `xs`, `sm`, `md`, `lg`, and `xl` size |
| 49 | +labels, with `md` size being the default, when no `size` property is passed in; |
| 50 | +- **`theme`** — *Object* — Button theme (we use |
| 51 | +[react-css-super-themr](https://www.npmjs.com/package/react-css-super-themr) |
| 52 | +to manage default / context / ad-hoc theming of components). This object is |
| 53 | +supposed to have the following fields: |
| 54 | + - **`button`** — *String* — The class to apply to the root element |
| 55 | + of the button in all cases; |
| 56 | + - **`disabled`** — *String* — The class to additionally apply to |
| 57 | + the root element of the button, when it is disabled; |
| 58 | + - **`link`** — *String* — Optional. The class to additionally |
| 59 | + apply to the root element of the button, when the button is rendered as |
| 60 | + `<Link>`; |
| 61 | + - **`regular`** — *String* — Optinal. The class to additionally |
| 62 | + apply to the root element of the button, when the button is rendered as |
| 63 | + `<button>`; |
| 64 | + - Other fields matching acceptable values of the `size` prop. Each of them |
| 65 | + will hold the class to additionally apply to the root element of the button, |
| 66 | + when the `<size>` value matches; |
| 67 | +- **`to`** — *Object* or *String* — When specified the button will |
| 68 | +be rendered as `<Link>` (if non-disabled), and it will point to the specified |
| 69 | +URL/location. |
| 70 | + |
| 71 | +### <a name="examples">Examples</a> |
| 72 | +Simple button: |
| 73 | +```js |
| 74 | +import { Button } from 'topcoder-react-utils'; |
| 75 | + |
| 76 | +export default function Example() { |
| 77 | + return <Button onClick={() => console.log('Clicked!')}>Click Me!</Button>; |
| 78 | +} |
| 79 | +``` |
0 commit comments