StudioComponents

https://sircfenner.github.io/StudioComponents
Admin
StudioComponents is a collection of React components for building Roblox Studio plugins that match...
Tokens:27,592
Snippets:234
Trust Score:9.7
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example usage of useTheme in a custom component

Source: https://sircfenner.github.io/StudioComponents/api/useTheme

This example shows a custom component using useTheme to get a color from the Studio theme and apply it to a Frame. The hook returns a StudioTheme instance, and the example uses theme:GetColor with Enum.StudioStyleGuideColor.ScriptBackground and Enum.StudioStyleGuideModifier.Default.

```lua
local function MyThemedComponent()
	local theme = useTheme()
	local color = theme:GetColor(
		Enum.StudioStyleGuideColor.ScriptBackground,
		Enum.StudioStyleGuideModifier.Default
	)
	return React.createElement("Frame", {
		BackgroundColor3 = color,
		...
	})
end
```

--------------------------------

### Install StudioComponents with npm

Source: https://sircfenner.github.io/StudioComponents/docs/getting-started

Installs the @sircfenner/studiocomponents package using npm.

```bash
npm install @sircfenner/studiocomponents  

```

--------------------------------

### Install StudioComponents with yarn

Source: https://sircfenner.github.io/StudioComponents/docs/getting-started

Installs the @sircfenner/studiocomponents package using yarn.

```bash
yarn add @sircfenner/studiocomponents  

```

--------------------------------

### Minimal StudioComponents component example

Source: https://sircfenner.github.io/StudioComponents/docs/getting-started

Shows how to require StudioComponents and render a Label component with React.createElement. Requires react-lua and StudioComponents installed.

```lua
local React = require(Packages.React)  
local StudioComponents = require(Packages.StudioComponents)  
  
local function MyComponent()  
    return React.createElement(StudioComponents.Label, {  
        Text = "Hello, from StudioComponents!"  
    })  
end  

```

--------------------------------

### usePlugin hook example

Source: https://sircfenner.github.io/StudioComponents/api/usePlugin

Shows how to call usePlugin inside a component to get the plugin instance. Requires a PluginProvider higher up in the tree.

```lua
local function MyComponent()
	local plugin = usePlugin()
	...
end
```

--------------------------------

### Button

Source: https://sircfenner.github.io/StudioComponents/api/Button

Documentation for the Button component, including its props and usage example.

```APIDOC
## [Component] Button

### Description
A basic button that supports text, an icon, or both. This should be used as a standalone button or as a secondary button alongside a MainButton for the primary action in a group of options.

### Props
- **Text** (string) - Optional - The text displayed on the button.
- **OnActivated** (function) - Optional - A callback which is run when the button is clicked.
- **Size** (UDim2) - Optional - Overrides the default button size.
- **AutomaticSize** (Enum.AutomaticSize) - Optional - Overrides the button's width and/or height to fit the text and/or icon. Passing `Enum.AutomaticSize.X` overrides width, `Enum.AutomaticSize.Y` overrides height, and `Enum.AutomaticSize.XY` overrides both axes.

### Example
```lua
local function MyComponent()
	return React.createElement(StudioComponents.Button, {
		Text = "Click Me",
		OnActivated = function()
			print("Button clicked!")
		end
	})
end
```

### Notes
- The default size of buttons can be found in `Constants.DefaultButtonHeight`.
- The `AutomaticSize` prop is a simpler version of Roblox's built-in AutomaticSize system.
```

--------------------------------

### Slider usage example

Source: https://sircfenner.github.io/StudioComponents/api/Slider

Shows a complete example of using the Slider component with React. It uses useState to manage the value and passes Value, OnChanged, Min, Max, and Step props.

```lua
local function MyComponent()
	local value, setValue = React.useState(1)
	return React.createElement(StudioComponents.Slider, {
		Value = value,
		OnChanged = setValue,
		Min = 0,
		Max = 10,
		Step = 1,
	})
end
```

--------------------------------

### TextInput

Source: https://sircfenner.github.io/StudioComponents/api/TextInput

Documentation for the TextInput component, including its props and usage examples.

```APIDOC
## TextInput

### Description
A basic input field for entering any kind of text. This matches the appearance of the search boxes in the Explorer and Properties widgets, among other inputs in Studio. This is a controlled component, which means the current text should be passed in to the `Text` prop and a callback value to the `OnChanged` prop which gets run when the user attempts types in the input field.

### Props
- **Text** (string) - Required - The current text to display in the input field.
- **OnChanged** (function) - Required - Callback that is called with the new text when the user types in the input field.

### Example
```lua
local function MyComponent()
	local text, setText = React.useState("")
	return React.createElement(StudioComponents.TextInput, {
		Text = text,
		OnChanged = setText,
	})
end
```

### Notes
- By default, the height of this component is equal to the value in `Constants.DefaultInputHeight`. While this can be overridden by props, in order to keep inputs accessible it is not recommended to make the component any smaller than this.
```

--------------------------------

### Button Component

Source: https://sircfenner.github.io/StudioComponents/api/Button

Documentation for the Button component, including its props and usage example.

```APIDOC
## Button Component

### Description
A basic button that supports text, an icon, or both. This should be used as a standalone button or as a secondary button alongside a MainButton for the primary action in a group of options.

### Props

#### CommonProps
- **...** (CommonProps) - Required - Inherits all properties from CommonProps.

#### AutomaticSize
- **AutomaticSize** (AutomaticSize?) - Optional - Overrides the button's width and/or height to fit the text and/or icon. Accepts `Enum.AutomaticSize.X`, `Enum.AutomaticSize.Y`, or `Enum.AutomaticSize.XY`.

#### OnActivated
- **OnActivated** (() -> ())? - Optional - A callback that is run when the button is clicked.

#### Text
- **Text** (string?) - Optional - The text displayed on the button.

#### Icon
- **Icon** (IconProps?) - Optional - Configuration for an icon displayed on the button.

### IconProps

#### Image
- **Image** (string) - Required - The image asset ID or path for the icon.

#### Size
- **Size** (Vector2) - Required - The size of the icon.

#### Transparency
- **Transparency** (number?) - Optional - The transparency of the icon.

#### Color
- **Color** (Color3?) - Optional - The color of the icon. At most one of `Color` and `UseThemeColor` should be specified.

#### UseThemeColor
- **UseThemeColor** (boolean?) - Optional - Whether to use the theme color for the icon. At most one of `Color` and `UseThemeColor` should be specified.

#### Alignment
- **Alignment** (HorizontalAlignment?) - Optional - Which side of any text the icon appears on. Left-alignment is the default and center-alignment is not supported.

#### ResampleMode
- **ResampleMode** (Enum.ResamplerMode?) - Optional - The resampling mode for the icon image.

#### RectOffset
- **RectOffset** (Vector2?) - Optional - The offset of the icon's image rect.

#### RectSize
- **RectSize** (Vector2?) - Optional - The size of the icon's image rect.

### Usage Example

```lua
local function MyComponent()
	return React.createElement(StudioComponents.Button, {
		Text = "Click Me",
		OnActivated = function()
			print("Button clicked!")
		end
	})
end
```
```

--------------------------------

### Usage example for PluginProvider

Source: https://sircfenner.github.io/StudioComponents/api/PluginProvider

Shows how to wrap your plugin's components with PluginProvider, passing the plugin instance and children. This is typically done at the top of the tree.

```lua
local function MyComponent()
	return React.createElement(StudioComponents.PluginProvider, {
		Plugin = plugin,
	}, {
		MyExample = React.createElement(MyExample, ...)
	})
end
```

--------------------------------

### TextInput Component

Source: https://sircfenner.github.io/StudioComponents/api/TextInput

Documentation for the TextInput component, including its props and usage examples.

```APIDOC
## TextInput Component

### Description
A basic input field for entering any kind of text. This matches the appearance of the search boxes in the Explorer and Properties widgets, among other inputs in Studio. This is a controlled component, meaning the current text should be passed in via the `Text` prop and a callback value to the `OnChanged` prop which gets run when the user types in the input field.

### Props

#### `...` (CommonProps) - Required - Inherits common props from `CommonProps`.

#### `Text` (string) - Required - The current text to display in the input field.

#### `OnChanged` ((newText: string) -> ())? - Optional - Callback that is invoked when the user types in the input field. Receives the new text as a parameter.

#### `PlaceholderText` (string?)? - Optional - Placeholder text to display when the input is empty.

#### `ClearTextOnFocus` (boolean?)? - Optional - If true, clears the text when the input gains focus.

#### `OnFocused` (() -> ())? - Optional - Callback that is invoked when the input gains focus.

#### `OnFocusLost` ((text: string, enterPressed: boolean, input: InputObject) -> ())? - Optional - Callback that is invoked when the input loses focus. Receives the current text, whether the enter key was pressed, and the input object.

### Usage Example

```lua
local function MyComponent()
	local text, setText = React.useState("")
	return React.createElement(StudioComponents.TextInput, {
		Text = text,
		OnChanged = setText,
	})
end
```

### Filtering Example

```lua
local function MyComponent()
	local text, setText = React.useState("")
	return React.createElement(StudioComponents.TextInput, {
		Text = text,
		OnChanged = function(newText)
			local filteredText = string.gsub(newText, "[^a-z]", "")
			setText(filteredText)
		end,
	})
end
```

### Notes
By default, the height of this component is equal to the value in `Constants.DefaultInputHeight`. While this can be overridden by props, in order to keep inputs accessible it is not recommended to make the component any smaller than this.
```

--------------------------------

### ScrollFrame with custom Layout

Source: https://sircfenner.github.io/StudioComponents/api/ScrollFrame

Example showing how to create a ScrollFrame with a custom UIListLayout, including padding and horizontal fill direction. Children are passed as a table to createElement.

```lua
local function MyComponent()
	return React.createElement(StudioComponents.ScrollFrame, {
		Layout = {
			ClassName = "UIListLayout",
			Padding = UDim.new(0, 10),
			FillDirection = Enum.FillDirection.Horizontal,
		}
	}, {
		SomeChild = React.createElement(...),
		AnotherChild = React.createElement(...),
	})
end
```

--------------------------------

### Checkbox

Source: https://sircfenner.github.io/StudioComponents/api/Checkbox

Documentation for the Checkbox component, including its props and usage example.

```APIDOC
## Checkbox Component

### Description
A box which can be checked or unchecked, usually used to toggle an option. Passing a value to the `Label` prop is the recommended way to indicate the purpose of a checkbox.

### Props

#### Label
- **Type**: string
- **Required**: No
- **Description**: Text to indicate the purpose of the checkbox.

#### Value
- **Type**: boolean or nil
- **Required**: Yes (controlled component)
- **Description**: Represents whether the box is checked. Pass `nil` to represent an indeterminate state.

#### OnChanged
- **Type**: callback function
- **Required**: Yes (controlled component)
- **Description**: Callback that runs when the user interacts with the checkbox.

#### Size
- **Type**: UDim2
- **Required**: No
- **Description**: Overrides the size of the whole checkbox. Default height can be found in `Constants.DefaultToggleHeight`.

#### ContentAlignment
- **Type**: Enum.HorizontalAlignment
- **Required**: No
- **Description**: Overrides the alignment of the box and label within the parent frame. Default is left-aligned.

#### ButtonAlignment
- **Type**: Enum.HorizontalAlignment
- **Required**: No
- **Description**: Overrides the placement of the box relative to the label. Default is left. Pass `Enum.HorizontalAlignment.Left` or `Enum.HorizontalAlignment.Right`.

### Example
```lua
local function MyComponent()
	local selected, setSelected = React.useState(false)
	return React.createElement(StudioComponents.Checkbox, {
		Value = selected,
		OnChanged = setSelected,
	})
end
```
```

--------------------------------

### Dropdown Basic Usage

Source: https://sircfenner.github.io/StudioComponents/api/Dropdown

Example of using the Dropdown component with a list of string items and managing the selected item with React state.

```APIDOC
## Dropdown Component

### Description
A togglable popup box containing a list of items to select a single item from. Clicking the top section opens the list; selecting an item, clicking elsewhere, or pressing Escape closes it. The list renders above all other UI elements under the same LayerCollector.

### Props
- **Items** (array of string or DropdownItemDetail) - Required - The list of items to display.
- **SelectedItem** (string) - Required - The currently selected item's value (or Id when using detailed items).
- **OnItemSelected** (function) - Required - Callback invoked when the user selects an item. Receives the selected item's value (or Id).
- **ClearButton** (boolean) - Optional - When true, allows the user to clear the selection.
- **Size** (UDim2) - Optional - Custom height for the top row. Default is Constants.DefaultDropdownHeight.
- **RowHeight** (number) - Optional - Height of each list row. Default is Constants.DefaultDropdownRowHeight.
- **MaxVisibleRows** (number) - Optional - Maximum number of visible rows in the list.

### Usage Example
```lua
local function MyComponent()
	local selected, setSelected = React.useState("Red")
	local items = {"Red", "Green", "Blue"}
	return React.createElement(StudioComponents.Dropdown, {
		Items = items,
		SelectedItem = selected,
		OnItemSelected = setSelected,
	})
end
```
```

--------------------------------

### Checkbox usage example

Source: https://sircfenner.github.io/StudioComponents/api/Checkbox

Shows how to use the Checkbox component with React, using useState to manage the checked state and passing the setter to OnChanged.

```lua
local function MyComponent()
	local selected, setSelected = React.useState(false)
	return React.createElement(StudioComponents.Checkbox, {
		Value = selected,
		OnChanged = setSelected,
	})
end
```

--------------------------------

### Dropdown with Detailed Items

Source: https://sircfenner.github.io/StudioComponents/api/Dropdown

Example of using the Dropdown component with a DropdownItemDetail array to display custom text and icons.

```APIDOC
## Dropdown Component with Detailed Items

### Description
When using the detailed item format, each item can have an Id, Text, and Icon. The SelectedItem and OnItemSelected values correspond to the Id field.

### DropdownItemDetail Fields
- **Id** (string) - Required - Unique identifier for the item.
- **Text** (string) - Required - Display text for the item.
- **Icon** (table) - Optional - Icon properties, e.g., { Image = "rbxassetid://..." }.

### Usage Example
```lua
local function MyComponent()
	local items = {
		{
			Id = "item-1",
			Text = "First Item",
			Icon = {
				Image = "rbxassetid://...",
				-- other icon properties
			},
		},
		-- more items
	}
	return React.createElement(StudioComponents.Dropdown, {
		Items = items,
		SelectedItem = "item-1",
		-- OnItemSelected callback
	})
end
```
```

--------------------------------

### Slider Component Usage

Source: https://sircfenner.github.io/StudioComponents/api/Slider

Example of using the Slider component with required and optional props.

```APIDOC
## Slider Component

### Description
A controlled component for selecting a numeric value from a range. Users must provide a value and a callback for changes, along with Min and Max props. Optional Step, OnCompleted, Border, and Background props are supported.

### Props
- **Value** (number) - Required - The current value of the slider.
- **OnChanged** (function) - Required - Callback invoked when the user changes the value.
- **Min** (number) - Required - The minimum value of the range.
- **Max** (number) - Required - The maximum value of the range.
- **Step** (number) - Optional - The increment for the slider. Defaults to 0, allowing any value in the range.
- **OnCompleted** (function) - Optional - Callback invoked with the latest value when sliding finishes, or if the component becomes disabled or unmounted during sliding.
- **Border** (boolean) - Optional - Determines whether a border is drawn. Defaults to true.
- **Background** (boolean) - Optional - Determines whether a visible background is shown. If false, border is hidden. Defaults to true.

### Example
```lua
local function MyComponent()
	local value, setValue = React.useState(1)
	return React.createElement(StudioComponents.Slider, {
		Value = value,
		OnChanged = setValue,
		Min = 0,
		Max = 10,
		Step = 1,
	})
end
```

### Notes
- The default height is equal to Constants.DefaultSliderHeight. It is not recommended to make the component smaller than this for accessibility.
```

--------------------------------

### useMouseIcon example: set and clear icon on hover and unmount

Source: https://sircfenner.github.io/StudioComponents/api/useMouseIcon

Shows a component using useMouseIcon to set a custom icon on hover and clear it on hover end and on unmount. Requires a PluginProvider higher up. The icon stack means the most recent setIcon call wins; clearIcon removes this component's icon, possibly falling back to another.

```lua
local function MyComponent()
	local mouseIconApi = useMouseIcon()

	React.useEffect(function() -- clear icon on unmount
		return function()
			mouseIconApi.clearIcon()
		end
	end, {})

	return React.createElement(SomeComponent, {
		OnHoverStart = function()
			mouseIconApi.setIcon(...) -- some icon for hover
		end,
		OnHoverEnd = function()
			mouseIconApi.clearIcon()
		end
	})
end
```

--------------------------------

### Usage example: React.createElement(StudioComponents.LoadingDots, {})

Source: https://sircfenner.github.io/StudioComponents/api/LoadingDots

Creates a LoadingDots component inside a custom component. Use for short loading processes where progress detail is unnecessary.

```lua
local function MyComponent()
	return React.createElement(StudioComponents.LoadingDots, {})
end
```

--------------------------------

### Label Component Usage

Source: https://sircfenner.github.io/StudioComponents/api/Label

Example of creating an error message label using the Label component with a TextColorStyle prop.

```APIDOC
## Label Component

### Description
A basic text label with default styling to match built-in labels as closely as possible. Text color matches the current theme's MainText color by default, but can be overridden via the `TextColorStyle` or `TextColor3` props.

### Props
- **Text** (string) - The text content of the label.
- **TextColorStyle** (Enum.StudioStyleGuideColor) - Optional. Preferred way to recolor text; uses the correct version of the color for the user's current theme.
- **TextColor3** (Color3) - Optional. Useful when a color is not represented by any StudioStyleGuideColor or should remain constant regardless of theme.

### Children
Any children passed to the component are parented to the underlying TextLabel instance. Useful for adding padding, UIStroke, or UIGradient.

### Defaults
- Font: Constants.DefaultFont
- TextSize: Constants.DefaultTextSize
These cannot be overridden via props.

### Example
```lua
local function MyComponent()
	return React.createElement(StudioComponents.Label, {
		Text = "Please enter at least 5 characters!",
		TextColorStyle = Enum.StudioStyleGuideColor.ErrorText,
	})
end
```
```

--------------------------------

### Splitter Component Usage

Source: https://sircfenner.github.io/StudioComponents/api/Splitter

Example of using the Splitter component with React, including state management and rendering children on both sides.

```APIDOC
## Splitter Component

### Description
A container frame split into two panels with a draggable control for resizing. The split location is controlled via the `Alpha` prop and updated via the `OnChanged` callback.

### Props
- **Alpha** (number) - Required - The current split location, a number between 0 and 1.
- **OnChanged** (function) - Required - Callback invoked with the new alpha value when the user resizes the splitter.
- **MinAlpha** (number) - Optional - Minimum alpha value, defaults to 0.1.
- **MaxAlpha** (number) - Optional - Maximum alpha value, defaults to 0.9.
- **FillDirection** (Enum.FillDirection) - Optional - Direction of the split. Default is horizontal (left/right). Use vertical for top/bottom.

### Children
- **Side0** (React element) - Required - Content for the first side (left or top depending on direction).
- **Side1** (React element) - Required - Content for the second side (right or bottom depending on direction).

### Example
```lua
local function MyComponent()
	local division, setDivision = React.useState(0.5)
	return React.createElement(StudioComponents.Splitter, {
		Alpha = division,
		OnChanged = setDivision,
	}, {
		Side0 = React.createElement(...),
		Side1 = React.createElement(...),
	})
end
```

### Notes
- This is a controlled component; the split location must be managed by the parent.
- To use system splitter mouse icons, ensure a PluginProvider is rendered higher up in the tree.
```

--------------------------------

### Splitter usage with React.createElement

Source: https://sircfenner.github.io/StudioComponents/api/Splitter

Shows a complete example of using StudioComponents.Splitter in a React component. The Alpha prop is controlled by state, and OnChanged updates it. Children are passed with Side0 and Side1 keys.

```lua
local function MyComponent()
	local division, setDivision = React.useState(0.5)
	return React.createElement(StudioComponents.Splitter, {
		Alpha = division,
		OnChanged = setDivision,
	}, {
		Side0 = React.createElement(...),
		Side1 = React.createElement(...),
	})
end
```

--------------------------------

### Create error message label with Label component

Source: https://sircfenner.github.io/StudioComponents/api/Label

Example of creating a Label with error text styling using TextColorStyle set to Enum.StudioStyleGuideColor.ErrorText.

```lua
local function MyComponent()
	return React.createElement(StudioComponents.Label, {
		Text = "Please enter at least 5 characters!",
		TextColorStyle = Enum.StudioStyleGuideColor.ErrorText,
	})
end
```

--------------------------------

### Using TabContainer with SelectedTab and OnTabSelected

Source: https://sircfenner.github.io/StudioComponents/api/TabContainer

Example of creating a TabContainer component with React, passing the selected tab state and a setter, and providing tab content via children. The keys in the children table are used as tab names and must correspond to the SelectedTab identifier and the identifiers passed to OnTabSelected.

```lua
local function MyComponent()
	local selectedTab, setSelectedTab = React.useState("Models")
	return React.createElement(TabContainer, {
		SelectedTab = selectedTab,
		OnTabSelected = setSelectedTab,
	}, {
		["Models"] = {
			LayoutOrder = 1,
			Content = React.createElement(...),
		},
		["Decals"] = {
			LayoutOrder = 2,
			Content = React.createElement(...),
		}
	})
end
```

--------------------------------

### TabContainer Component Usage

Source: https://sircfenner.github.io/StudioComponents/api/TabContainer

Example of using TabContainer in a React component, showing how to manage the selected tab state and pass tab content.

```APIDOC
## TabContainer Component

### Description
A controlled component that displays one content page at a time, with tabs along the top for selection. The selected tab is controlled via the `SelectedTab` prop and the `OnTabSelected` callback.

### Props
- **SelectedTab** (string) - Required - The identifier of the currently selected tab.
- **OnTabSelected** (function) - Required - Callback invoked when the user selects a tab. Receives the identifier of the selected tab.
- **Disabled** (boolean) - Optional - Disables the entire component when true.
- **children** (table) - Required - A table where keys are tab names and values are tables with `LayoutOrder` (number) and `Content` (React element) fields.

### Tab Entry Properties
- **LayoutOrder** (number) - Required - Determines the order of the tab in the tab controls.
- **Content** (React element) - Required - The content to render in the tab's main window.
- **Disabled** (boolean) - Optional - When true, disables the individual tab, making it unselectable.

### Example
```lua
local function MyComponent()
	local selectedTab, setSelectedTab = React.useState("Models")
	return React.createElement(TabContainer, {
		SelectedTab = selectedTab,
		OnTabSelected = setSelectedTab,
	}, {
		["Models"] = {
			LayoutOrder = 1,
			Content = React.createElement(...),
		},
		["Decals"] = {
			LayoutOrder = 2,
			Content = React.createElement(...),
		}
	})
end
```
```

--------------------------------

### Basic Slider usage with React

Source: https://sircfenner.github.io/StudioComponents/api/Slider

Example of using the Slider component with React hooks. Requires Value, OnChanged, Min, and Max props. Step is optional and defaults to 0.

```lua
local function MyComponent()
	local value, setValue = React.useState(1)
	return React.createElement(StudioComponents.Slider, {
		Value = value,
		OnChanged = setValue,
		Min = 0,
		Max = 10,
		Step = 1,
	})
end

```

--------------------------------

### Use ColorPicker with Value and OnChanged props

Source: https://sircfenner.github.io/StudioComponents/api/ColorPicker

Controlled usage example. Pass the current color to the `Value` prop and a callback to `OnChanged`, which is called when the user changes the color.

```lua
local function MyComponent()
	local color, setColor = React.useState(Color3.fromHex("#008080"))
	return React.createElement(StudioComponents.ColorPicker, {
		Value = color,
		OnChanged = setColor,
	})
end
```

--------------------------------

### Add studiocomponents to wally.toml

Source: https://sircfenner.github.io/StudioComponents/docs/getting-started

Adds the studiocomponents dependency to a Wally configuration file.

```toml
studiocomponents = "sircfenner/studiocomponents@1.0.0"  

```

--------------------------------

### useTheme()

Source: https://sircfenner.github.io/StudioComponents/api/useTheme

A hook that returns the current StudioTheme instance. Use it in custom components to read theme colors and style values.

```APIDOC
## useTheme()

### Description
Returns the current StudioTheme instance. This hook is used internally by components to read the selected Studio Theme and visually theme components appropriately. It is exposed so custom components can use the same API.

### Returns
- **StudioTheme** - The current StudioTheme instance.

### Example
```lua
local function MyThemedComponent()
	local theme = useTheme()
	local color = theme:GetColor(
		Enum.StudioStyleGuideColor.ScriptBackground,
		Enum.StudioStyleGuideModifier.Default
	)
	return React.createElement("Frame", {
		BackgroundColor3 = color,
		...
	})
end
```
```

--------------------------------

### Create a Background component with a child

Source: https://sircfenner.github.io/StudioComponents/api/Background

Use this snippet to create a Background component as the root of a plugin Widget. Any children passed are parented to the frame.

```lua
local function MyComponent()
	return React.createElement(StudioComponents.Background, {}, {
		MyChild = React.createElement(...),
	})
end
```

--------------------------------

### Props

Source: https://sircfenner.github.io/StudioComponents/api/MainButton

Defines the properties for the MainButton component.

```APIDOC
## Props

### Description
Defines the properties for the MainButton component.

### Fields
- **...** (CommonProps) - Required - Inherits common props from the base Button component.
- **AutomaticSize** (AutomaticSize?) - Optional - Controls automatic sizing behavior.
- **OnActivated** (() -> ())? - Optional - Callback function invoked when the button is activated.
- **Text** (string?) - Optional - The text displayed on the button.
- **Icon** (IconProps?) - Optional - Configuration for an icon displayed on the button.
```

--------------------------------

### Basic ProgressBar with Value and Max props

Source: https://sircfenner.github.io/StudioComponents/api/ProgressBar

Pass a number to Value and optionally to Max (defaults to 1). Value should be between 0 and Max.

```lua
local function MyComponent()
	return React.createElement(StudioComponents.ProgressBar, {
		Value = 5, -- loaded 5 items
		Max = 10, -- out of a total of 10 items
	})
end
```

--------------------------------

### Dropdown with Detailed Items and Icons

Source: https://sircfenner.github.io/StudioComponents/api/Dropdown

Shows how to use the DropdownItemDetail format to display custom text and icons. The SelectedItem and OnItemSelected values correspond to the Id field of the items.

```lua
local function MyComponent()
	local items = {
		{
			Id = "item-1",
			Text = "First Item",
			Icon = {
				Image = "rbxassetid://...",
				...
			},
		},
		...
	}
	...
	return React.createElement(StudioComponents.Dropdown, {
		Items = items,
		SelectedItem = "item-1",
		...
	})
end
```

--------------------------------

### Controlled Checkbox with useState

Source: https://sircfenner.github.io/StudioComponents/api/Checkbox

Example of using the Checkbox component as a controlled component with React state. Pass the selected state to the Value prop and the setter to OnChanged.

```lua
local function MyComponent()
	local selected, setSelected = React.useState(false)
	return React.createElement(StudioComponents.Checkbox, {
		Value = selected,
		OnChanged = setSelected,
	})
end

```

--------------------------------

### Custom Formatter for ProgressBar

Source: https://sircfenner.github.io/StudioComponents/api/ProgressBar

Provide a Formatter function that takes current and max values and returns a string to display instead of the default percentage.

```lua
local function MyComponent()
	return React.createElement(StudioComponents.ProgressBar, {
		Value = 3,
		Max = 20,
		Formatter = function(current, max)
			return `Loaded {current} / {max} assets...`
		end,
	})
end
```

--------------------------------

### RadioButton controlled component usage with React.useState

Source: https://sircfenner.github.io/StudioComponents/api/RadioButton

RadioButton is a controlled component, so it does not manage its own selected state. Pass a value to the Value prop and a callback to the OnChanged prop. The example uses React.useState to hold the selected state and passes setSelected as the OnChanged callback.

```lua
local function MyComponent()
	local selected, setSelected = React.useState(false)
	return React.createElement(StudioComponents.RadioButton, {
		Value = selected,
		OnChanged = setSelected,
	})
end

```

--------------------------------

### Controlled DatePicker usage with useState

Source: https://sircfenner.github.io/StudioComponents/api/DatePicker

Shows how to use the DatePicker as a controlled component: pass an initial date to the Date prop and a callback to OnChanged, which is called with the new date when the user selects one. The example uses React.useState to hold the date and React.createElement to render the component.

```lua
local function MyComponent()
	local date, setDate = React.useState(DateTime.now())
	return React.createElement(StudioComponents.DatePicker, {
		Date = date,
		OnChanged = setDate,
	})
end
```

--------------------------------

### usePlugin()

Source: https://sircfenner.github.io/StudioComponents/api/usePlugin

A hook that returns the root Plugin instance associated with the current plugin. It requires a single PluginProvider to be present higher up in the tree.

```APIDOC
## usePlugin()

### Description
A hook used to obtain a reference to the root [plugin](https://create.roblox.com/docs/reference/engine/classes/Plugin) instance associated with the current plugin. It requires a single [PluginProvider] to be present higher up in the tree.

### Usage Example
```lua
local function MyComponent()
	local plugin = usePlugin()
	...
end
```

### Returns
- **Plugin** - The root plugin instance associated with the current plugin.
```

--------------------------------

### Basic Dropdown with useState

Source: https://sircfenner.github.io/StudioComponents/api/Dropdown

Shows a controlled Dropdown component using React.useState to manage the selected item. The Dropdown requires SelectedItem and OnItemSelected props.

```lua
local function MyComponent()
	local selected, setSelected = React.useState("Red")
	local items = {	"Red", "Green", "Blue" }
	return React.createElement(StudioComponents.Dropdown, {
		Items = items,
		SelectedItem = selected,
		OnItemSelected = setSelected,
	})
end
```

--------------------------------

### Create DropShadowFrame with children

Source: https://sircfenner.github.io/StudioComponents/api/DropShadowFrame

Shows how to use DropShadowFrame in a React component, passing children like Label and Checkbox. Children are parented to the container frame.

```lua
local function MyComponent()
	return React.createElement(StudioComponents.DropShadowFrame, {}, {
		MyLabel = React.createElement(StudioComponents.Label, ...),
		MyCheckbox = React.createElement(StudioComponents.Checkbox, ...),
	})
end
```

--------------------------------

### Create an error message label with TextColorStyle

Source: https://sircfenner.github.io/StudioComponents/api/Label

Creates a Label with error text styling by passing Enum.StudioStyleGuideColor.ErrorText to the TextColorStyle prop. Use this when the label should reflect the user's current theme.

```lua
local function MyComponent()
	return React.createElement(StudioComponents.Label, {
		Text = "Please enter at least 5 characters!",
		TextColorStyle = Enum.StudioStyleGuideColor.ErrorText,
	})
end

```

--------------------------------

### Background Component

Source: https://sircfenner.github.io/StudioComponents/api/Background

The Background component is a borderless frame that matches the default background color of Studio widgets. It accepts common props and children, and is suitable for use as the root component in a plugin Widget.

```APIDOC
## Background Component

### Description
A borderless frame matching the default background color of Studio widgets. Any children passed will be parented to the frame, making it suitable for use as the root component in a plugin Widget.

### Props
- **...** (CommonProps) - Required - Common props for the component.
- **children** (React.ReactNode) - Required - The children to be parented to the frame.

### Example
```lua
local function MyComponent()
	return React.createElement(StudioComponents.Background, {}, {
		MyChild = React.createElement(...),
	})
end
```
```

--------------------------------

### Basic Dropdown with string items

Source: https://sircfenner.github.io/StudioComponents/api/Dropdown

Shows a controlled Dropdown using React.useState to manage the selected item. The Items prop is a list of strings, and OnItemSelected is set to the state setter.

```lua
local function MyComponent()
	local selected, setSelected = React.useState("Red")
	local items = {	"Red", "Green", "Blue" }
	return React.createElement(StudioComponents.Dropdown, {
		Items = items,
		SelectedItem = selected,
		OnItemSelected = setSelected,
	})
end

```

--------------------------------

### Dropdown with detailed item format

Source: https://sircfenner.github.io/StudioComponents/api/Dropdown

Shows how to use DropdownItemDetail array to display custom text and icons. The SelectedItem and OnItemSelected values correspond to the Id field of each item.

```lua
local function MyComponent()
	local items = {
		{
			Id = "item-1",
			Text = "First Item",
			Icon = {
				Image = "rbxassetid://...",
				...
			},
		},
		...
	}
	...
	return React.createElement(StudioComponents.Dropdown, {
		Items = items,
		SelectedItem = "item-1",
		...
	})
end

```

--------------------------------

### Basic TextInput usage with useState

Source: https://sircfenner.github.io/StudioComponents/api/TextInput

Creates a controlled TextInput component. The current text is stored in state and passed to the Text prop, while the OnChanged prop is set to the state setter function.

```lua
local function MyComponent()
	local text, setText = React.useState("")
	return React.createElement(StudioComponents.TextInput, {
		Text = text,
		OnChanged = setText,
	})
end
```

--------------------------------

### DropdownItemIcon

Source: https://sircfenner.github.io/StudioComponents/api/Dropdown

Defines the properties for an icon used in a dropdown item.

```APIDOC
## DropdownItemIcon

### Description
Defines the properties for an icon used in a dropdown item.

### Fields
- `Image` (string) - Required - The image asset for the icon.
- `Size` (Vector2) - Required - The size of the icon.
- `Transparency` (number?) - Optional - Transparency of the icon.
- `Color` (Color3?) - Optional - Color tint of the icon.
- `UseThemeColor` (boolean?) - Optional - Whether to use the theme color.
- `ResampleMode` (Enum.ResamplerMode?) - Optional - Resampling mode for the image.
- `RectOffset` (Vector2?) - Optional - Offset of the image rectangle.
- `RectSize` (Vector2?) - Optional - Size of the image rectangle.
```
Tokens:
Raw