@kiwicom/orbit-components
Version:
Orbit-components is a React component library which provides developers with the easiest possible way of building Kiwi.com's products.
107 lines • 6.89 kB
TypeScript
import * as React from "react";
import type { Props } from "./types";
/**
* @orbit-doc-start
* README
* ----------
* # ChoiceGroup
*
* To implement ChoiceGroup component into your project you'll need to add the import:
*
* ```jsx
* import ChoiceGroup from "@kiwicom/orbit-components/lib/ChoiceGroup";
* import Radio from "@kiwicom/orbit-components/lib/Radio";
* ```
*
* After adding import into your project you can use it simply like:
*
* ```jsx
* <ChoiceGroup label="What was the reason for your cancellation?">
* <Radio label="Reason one" value="one" />
* <Radio label="Reason two" value="two" />
* <Radio label="Reason three" value="three" />
* </ChoiceGroup>
* ```
*
* ## Props
*
* Table below contains all types of the props available in the ChoiceGroup component.
*
* | Name | Type | Default | Description |
* | :---------------- | :---------------------------------------------------------------- | :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
* | dataTest | `string` | | Optional prop for testing purposes. |
* | id | `string` | | Set `id` for `ChoiceGroup` |
* | **children** | `React.Node ` | `(args) => React.Node` | The content of the ChoiceGroup, normally **Radio** or **Checkbox**. Pass a function for advanced usage, see "Render prop" in Storybook for an example. |
* | error | `Translation` | | The error to display beneath the ChoiceGroup. Also, the Checkboxes/Radios will turn red when you pass some value. |
* | label | `Translation` | | Heading text of the ChoiceGroup |
* | labelAs | [`enum`](#enum) | `"div"` | The element used to render the label into. |
* | labelSize | [`enum`](#enum) | `"normal"` | The size type of Heading. |
* | **onChange** | `event => void \| Promise` | | Function for handling onChange event. [See Functional specs](#functional-specs) |
* | filter | `boolean` | `false` | Changes visual appearance of child components, to contain background on hover and updates padding. |
* | onOnlySelection | `(event, {value: string, label: string}) => void \| Promise<any>` | | Function for handling onOnlySelection, read more in Functional specs. |
* | onlySelectionText | `Translation` | | Property for passing translation string when you want to use the `onOnlySelection` callback. |
*
* ### enum
*
* | labelElement | labelSize |
* | :----------- | :--------- |
* | `"h2"` | `"normal"` |
* | `"h3"` | `"large"` |
* | `"h4"` |
* | `"h5"` |
* | `"h6"` |
*
* ### Passing a function as `children`
*
* If you need more control over how to render ChoiceGroup, for example using [`react-window`](https://github.com/bvaughn/react-window), you can pass a function to `children` instead of `React.Node`, which receives an object containing the following properties:
*
* - `Container` is the inner container where Radio/Checkbox elements are placed
* - `Item` is the component that should wrap Radio/Checkbox elements
* - `spacing` is the spacing between items, which you need to apply yourself
*
* This is a barebones example:
*
* ```jsx
* <ChoiceGroup onChange={ev => doSomething(ev)}>
* {({ Container, Item, spacing }) => (
* <Container style={{ display: "flex", flexDirection: "column", gap: spacing }}>
* <Item>
* <Radio label="Reason one" value="two" />
* </Item>
* <Item>
* <Radio label="Reason two" value="two" />
* </Item>
* <Item>
* <Radio label="Reason three" value="three" />
* </Item>
* </Container>
* )}
* </ChoiceGroup>
* ```
*
* For more realistic usage you can check out the "Render prop" example in Storybook.
*
* ## Functional specs
*
* - onChange props in `<Radio />` or `<Checkbox />` will be overridden by internal onChange function
* - If you want to handle selecting field, pass `onChange` to `<ChoiceGroup />` and it will be always triggered when `<Radio />` or `<Checkbox />` should change
* - `onChange` will return `SyntheticEvent` of field that should change
*
* ```jsx
* <ChoiceGroup onChange={ev => doSomething(ev)}>
* <Radio label="Reason one" value="one" />
* <Radio label="Reason two" value="two" />
* <Radio label="Reason three" value="three" />
* </ChoiceGroup>
* ```
*
* - `onOnlySelection` can be used only when `filter` prop is used.
* - `filter` pattern with `onOnlySelection` is used where multiple checkboxes in different states are presented to the user, and the user wants to choose only one of them.
* - `filter` pattern with `onOnlySelection` shouldn't contain radio buttons.
*
*
* @orbit-doc-end
*/
declare const ChoiceGroup: ({ dataTest, id, label, labelSize, labelAs, error, children, filter, onOnlySelection, onlySelectionText, onChange, ref, }: Props) => React.JSX.Element;
export default ChoiceGroup;
//# sourceMappingURL=index.d.ts.map